Technical writers, DITA, wikis and hippies
Today I attended a DITA training course presented by Tactics Consulting and Tony Self of Hyperwrite. It is always a pleasure to listen to Tony. He has such a charming way of conveying information that could otherwise be considered dry and boring by some😉
I thoroughly enjoyed the wry humour that inevitably happens when technical writers find themselves in the same room together. Tony told us how Darwin and the finches got together with the hippies to produce an XML documentation standard just for us.
The course was centred around structured authoring methodologies with DITA as the tool. My primary interest is the feasibility of having DITA as a supported output from a wiki. Confluence, to be specific.
Clever people have spent thousands of hours devising DITA, and will continue to do so. How awesome if our product documentation could hook into this cleverness for purposes like these:
- Delivering content in different media such as PDF, Postscript, HTML, RTF.
- Converting content to other authoring environments, including other wikis. This would be useful for our customers who have products like Bamboo or JIRA but use a different wiki. Or for customers who use Confluence to write their own product documentation which they need to pass on to their customers in turn.
- Localisation and reducing costs of translation e.g. by converting from DITA to XLIFF as an information exchange mechanism between us and the people who translate the documentation. Translation of our documentation is going to become more and more of a requirement.
- The ability to respond quickly to customers who request the documentation in some format that we don’t know about or support but for which someone has already created the DITA transformation.
At first, the wiki to DITA conversion would use only a subset of DITA capabilities. I’d suggest we don’t try to constrain the wiki authors by enforcing too much structure on the content. If we did that, we would run the risk of spoiling the flexible collaboration and quick authoring that are the heart of a wiki.
But we could still have enough typing to make the process worthwhile. We could map semantics which are naturally in the wiki markup to the corresponding DITA elements. The wiki could offer a more structured option for those who want to use it. One way might be for authors to tag a page as a concept, task or reference via labels or other metadata. Then we could perform an intelligent mapping of the information chunks within the page, falling back to the least typed content when necessary e.g. a concept.
It would not be a trivial task. I wouldn’t think of DITA as the primary authoring tool or even as the backend storage mechanism for the wiki content. Not yet, anyway. Instead, how awesome if Confluence could export compliant DITA, to a level of detail and even to a specialisation determined by the information architect.
These were the thoughts that wandered through my head while Tony guided us through the joys of WYSIOO (What You See Is One Option) and tools that are not ideal. He used a different word for that phrase😉
Thank you to Tactics for a great day, to Tony for his charm and skill and knowledge, and to the other tech writers on the course for … well, just for being tech writers. It was great to be with a bunch of people who know that it really matters where you put your semi-colon and whether the XSD allows for a stem sentence.