For reasons relating to work and incidentally for a presentation I am working on for the Baltimore DITA conference in April, I am trying to learn the practicalities of implementing DITA constraints. (For a list of the reasons why constraints are good, see this nice summary on Tagsmiths). Am currently plowing through the pertinent section in the DITA 1.2 spec, trying to use that information for what I hope will be a practical implementation that will keep the number of tags we use to those used in our house style. All of this reminded me of the presentation I attended by Jang F.M. Graat on this DITA constraints and specialization at the DITA conference in Vienna in November.
I took copious notes at most of the presentations I attended, so here is my summary and thoughts on Graat’s presentation, which I think was one of the more insightful (though maddeningly more theoretical than practical, for reasons which will become clear) that I attended at that conference.
DITA Constraints Presentation by Jang Graat
This was another talk at the conference I was looking forward to, as it is clear that the new constraint mechanism to be introduced in the forthcoming DITA 1.2 spec for limiting the number of tags in use will be useful. I was also personally intrigued since the presenter had come up to me after my talk the day before and politely disagreed with my approach to letting my team choose the tags they wanted to use and then winnowing our tag set down to what was used, rather than defining the usable tags from the outset. (I still think there is merit to this bottom-up approach within a small team that regularly edits each other’s topics, but more on that another time).
The presenter was Jang F.M. Graat who opened the talk by describing himself as “a philosopher who ended up going into the computer field”. As a result he considers himself to be more reflective than most programmers when it comes to understanding computer systems, including DITA. At this point my bullish*t detector went into overdrive, but I decided to keep an open mind, and in the end he delivered a genuinely thoughtful presentation on his subject.
He believes that constraints are among the most important aspect of the upcoming DITA 1.2 standard because he sees it as way to avoid an oncoming clash in current working DITA between minimalism and specialization. The following is what I took away from his presentation:
The case for minimalism is that users do not need more info, just enough to do the job. Technical writers taking a minimalist approach should ideally answer a single question in each topic, like:
• How do I do this?
• What went wrong?
• What are my options?
• What is this thing for?
• How does this work?
So ideally, each topic should work on its own, bringing its context along for the ride. If you need to understand something, a single pithy concept topic ought to do it. If you need to know how to accomplish something, a concise task topic should be able to guide you along. If you need basic information about how a widget is configured, a reference topic outlining the basic specification will have what you need. This is minimalism as applied to DITA in a nutshell.
But DITA also allows for specialization, which is there to adapt to specific and particular conditions, and so is not useful out of its own context. If you specialize a topic or tags so that it better fits a very specific need, it becomes less generalized and more “isolated” when it comes to such things as topic reuse. A good case in point: I remember advising someone at a previous conference not to specialize a topic for thing like address tables, because in the end (to paraphrase Gertrude Stein): “a table is a table is a table”. Having specific table types – while far from being an alien concept in XML – reduces reuse of that same information in un-specialized topics. (Where reuse is not an issue this does make sense; hello semiconductor specialization!)
Graat predicts that there may be thousands of specialized elements within another ten years, which would increase its complexity while greatly reducing it’s general applicability, as in the end more specialized elements means less reusability. At this point Graat showed a picture of a monster Swiss army knife which contained every possible tool, which as he said “can do just about anything, but is impractical to use”.
So saying he believes that the whole of DITA even as it currently stands has too many options, reducing its overall efficiency as a good, general-purpose tool.
This is where constraints in the upcoming DITA 1.2 spec comes to the rescue, as it provides a means to specialize without specialization, not by creating new elements, but by constraining your usage of DITA elements to those you actually use. This results in a writing team needing less than the full standard, usefully constraining what tags a writer can use in order have them better focus on the job that they are supposed to do. His take on using them was to start with the most constrained condition, and then loosen the constraints as required as needs evolve. He believes that constraints are DITA’s future, “a perfect fit for every occasion” and that they will save DITA from over-specializing itself into irrelevance.
Technically speaking, constraints live in mod files, which is essentially a modified DTD. Graat said they were easy to switch on or off, but were still too hard to edit for those without a thorough understanding of DTDs. One thing I didn’t know previously is that they can also be used to define required elements to ensure that authors include essential information.
At this point I was hoping he would present some good code examples, or better yet, a tool for doing the job. Graat then said that while he has in mind the design of a tool to do the job, he does not have the development skills to make It happen, and hoped that any development types in the audience may be able to help out. I don’t know if he had any takers, but he highlighted a key area that could be serviced by better software tools which do not currently exist. Some sort of interactive WYSIWYG tool in this area would be ideal so that no DTD specialists are required. In the meantime we’ll have to make do with our XML editors and hope we don’t break anything when trying to put together our own mod files.
He was a good and thoughtful speaker, and I can only hope that next time I see him he has some working tools to show off.
Turns out he will be at the Baltimore conference later this Spring, so am hoping he will have more to say there about any success he’s had with the tool he was hoping to build.
I value the article.Thanks Again. Cool.
Thanks for the article.
Jang F.M. Graat is spot on. The ability to create valid standard DITA, but in an editor that shows only the tags and attributes you need, is essential to DITA taking the next step – and moving into e.g. the developer’s and marketing content development toolbox.
Also in the documentation department reducing the tag set to what’s needed, will ease the change management when implementing DITA.
Furthermore, constraints help content developers be more consistent in tagging content. Let’s face it: We do structured writing, but the agreed structure never looks exactly the same in the in heads of two content developers. 😉
I see that your article is a couple of years old. I’d like to know if you have come across any WYSIWYG tools for implementing constraints in the mean time?