TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
First let me say, this has wandered pretty far from the stated thread subject. But that's the fun of it...
I have to take issue with some statements. I'll start with this one:
============
Traditional document structures tie you to the document structure youchoose. If you chose to use a list, it stays a list. If you chose to use a
table, it stays a table, because we don't know enough about the information
in those structures to do anything else with them.
===========
In terms of markup that simply isn't true. There are so many points to make:
I've switched over to LightWeight DITA -- XDITA as they call the XML implementation. I could rant forever about how less is more, and I still haven't had time to fully exploit the subset of XDITA that I currently use... But to the point, XDITA includes a DATA element, which means you can add arbitrary metadata to just about any element in the spec. This means you can capture whatever data you deem important... You can express subject domain and more if you wish.
We specifically had to implement a list as a table - FrameMaker has trouble with conrefs to table pieces and we wanted variable tables that use different rows depending on context. We implemented a definition list, and display it as a table in HTML -- no problem. I know that SAP injects javascript into their table representations to give them behavior -- a table is MORE than a table in that case.
But to really tackle this you have to ask what makes a table a table and not a list? Is it just the way you display it? Of course not. What makes a table is the 2D or 3D set of relationships... Or pivot table might have more dimensions. Rendering is just about taking advantage of those relationships. On paper you're often stuck with what we call tables, even if you could imagine a better way to represent the same information. Online docs can do other things -- I suggest you look at the d3.js gallery for ideas... It's pretty amazing!https://github.com/d3/d3/wiki/gallery
You can imagine I would say this... I've used d3 in docs to render tabular data in different ways. I've even done this with real-time data from the product I'm documenting. So a table can become an image, it can exhibit behavior, it can zoom in or out, it can express relationships in various ways. This is because the key to markup is separating data from rendering. So if you lump XML and even DITA, or even HTML in with "traditional document structure" then you simply cannot say a table is always and only a table. Unless you mean a multidimensional set of relationships between data points will always be a multidimensional set of relationships between data points.
It gets more interesting. I currently use DITA ordered lists (procedures) for the content of walk-throughs in the GUI... Balloons that point to the GUI widgets and give instructions. In the metadata I provide a selector for the widget and other display-related info. I transform the DITA into JSON, and we can do anything with it that we want. When I put the same procedure out to HTML or PDF, the metadata just falls through and it looks like a list in document. So a list is not always a list, either. Or well... A list is always a sequential grouping of individual points, but you can display it however you want.
Now our subject is a product -- More specifically a product GUI. I can exploit this domain to not only manage the narrative, but to also bring the product into the docs, and put the docs into the product. Have I implemented a model that guides me through authoring for this? No -- I have lots to say about that as you can imagine. But in terms of reaching beyond a document domain and into a subject domain, I believe I can demonstrate that it's entirely possible with XDITA, and that XDITA is nicely suited to the task.Â
Could there be something better than XDITA? Of course. But in the real world you have to use what's available. Also, XDITA has the benefit of a standards body, and lots of compatible tooling -- much of it free. And finally, XDITA is pretty simple. In spite of that simplicity, I challenge anybody out there to exhaust its potential. I'm sure I never will.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com
