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.
If you take a traditional document structure and add a bunch of subject domain metadata to it so that you know what is in each row and column, then is it no longer a traditional document structure. You have turned it into a record set. Perhaps it is a little more verbose in its markup than if you had set out from scratch to create a record set, but it is still a record set, and as such can be transformed into all kinds of things.
The key is to apply the appropriate metadata to the content so that you preserve the possibilities inherent in it. The syntax matters, in that a more verbose syntax is more overhead, but the fundamental properties are the same.
Can you do this in DITA? Yes. You moved your content to the subject domain in DITA, and that gives you the advantages of the subject domain. Congratulations. That's a good thing and I am glad to hear about it.
Is DITA the most elegant tool imaginable for doing this? No.
Do I think people using DITA should use features like these to move their content to the subject domain when it is beneficial to do so? Yes.
Am I happy to see DITA moving in the direction of providing greater support for working in the subject domain? Yes, absolutely. Getting people moving to the subject domain is my priority.
Do I acknowledge the value of using a widely-supported technology, even if it is not ideal in all its particulars? Yes.
Do I think DITA represents an end state of documentation technology beyond which no worthwhile development is possible or should be contemplated? No.
Mark
> -----Original Message-----
> From: techwr-l-bounces+mbaker=analecta -dot- com -at- lists -dot- techwr-l -dot- com
> [mailto:techwr-l-bounces+mbaker=analecta -dot- com -at- lists -dot- techwr-l -dot- com] On
> Behalf Of Chris Despopoulos
> Sent: Tuesday, May 2, 2017 6:45 AM
> To: techwr-l -at- lists -dot- techwr-l -dot- com
> Subject: RE: Structured stuff for the beginner
>
> 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
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as mbaker -at- analecta -dot- com -dot-
>
> To unsubscribe send a blank email to
> techwr-l-leave -at- lists -dot- techwr-l -dot- com
>
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
>http://www.techwhirl.com/email-discussion-groups/ for more resources and
> info.
>
> Looking for articles on Technical Communications? Head over to our online
> magazine at http://techwhirl.com
>
> Looking for the archived Techwr-l email discussions? Search our public email
> archives @ http://techwr-l.com/archives
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com
