[This is my first #techcomm blog post in about two years. That’s partly due to the fact that I no longer work in a conventional #techcomm job, but mainly because I’ve become a bit lazy in my old age!]
Write the Docs meetup on documentation formats
Last week I went to a WriteTheDocs meetup in London, where three speakers addressed the topic of “Format the Docs”, not in terms of visual appearance, but in terms of what format was best for technical documentation (details). The three formats discussed were DocBook, DITA, and somewhat surprisingly to some people, Microsoft Word.
The first speaker, Peter Desjardins (see details), explained that DocBook, an XML format, began to be developed in the early 1990s and was developed from SGML. DocBook is very common in open source projects, as it is easy to publish, easy to automate, and suitable for Apache based systems. It has an explicit structure, which means it’s easy for processing tools to work with. There are various free and commercial editors available for DocBook. Plain text source formats like DocBook can be stored in GitHub, which developers like. Using GitHub makes it easy to track and control changes, and easy to fork or branch. It also works well with automated build and continuous integration tools.
Some people complain that DocBook has too many elements. Peter pointed out, however, that if you are writing about Java classes and you can use a DocBook element called MethodDescription, that’s great. You can output DocBook through various XSLT Transformations (for example web help, or PDF), and some people feel that it takes a lot of effort to master XSLT and FO, but there is a load of helpful material available, so you can learn to write your own custom XSLT – Peter assured us tht looks more scary than it is. I wasn’t entirely convinced.
Bridget Rooney was the second speaker and described DITA, another XML tool for documentation, that separates content from presentation (see details). The DITA Open Toolkit (DITA-OT) is available for publishing. DITA users tend to compose content in separate topics, with standard element sets for Tasks, Concepts and references, and then use DITA-maps to select the topics you want to include in a particular publication. This makes DITA very suitable when some of your content can be re-used across many different publications.
Bridget acknowledged the disadvantage of DITA was that, as with DocBook, technical skills are needed for transforms and publications and explained that her company had a 2-stream team working on publications consisting of writers and “Doc-Ops” – programmers dedicated to supporting the publication process.
As someone who used to know a lot about DITA, Bridget’s talk made me realise that there has been significant progress in editing tools since I last used DITA, but that many of the obstacles to easy publishing still remained.
Richard Stamp was the last speaker and declared that Microsoft Word was actually a very powerful tool, very configurable, very customizable, mature, and stable tool, and is available on Windows PCs and Mac (see details). He said that the problem with Word wasn’t the tool itself, but the fact that 99% of users aren’t professionals, and therefore it was up to the 1% of professional users – such as #techcomm professionals – to show exactly how much could be done with Word.
Richard described three projects that he’d been involved in at different companies. The first made use of Word styles, and went beyond merely encouraging consistency. The project locked down the available down styles and disabled manual formatting, and customised the ribbon to make things more acceptable to non-professional users. Richard considered the customised ribbon to be critical for user acceptance. There were different templates available, each with their own styles, macros (linked to buttons on the ribbon) and autotexts.
The second project related to ensuring visual consistency for website content created by non-technical users, where locked down templates were not an option as each contributor was working independently from home. The solution involved porting from Word to Markdown (not too difficult technically, just a series of find-and-replace macros), and then from Markdown to Drupal (far more complicated but only needed to be set up once). Richard acknowledged that this solution probably would not have worked there had been tables involved. The third project involved procedure-heavy documentation using DITA, and publishing with the DITA_OT, but using Word as an editor. This involved a lot of round-tripping through various VBA routines and was feasible because Word’s .docx format is really just a ZIP file full of XML-like elements, and because the project was at a really technical company.
I apologise to all of the speakers if this brief summary hasn’t done them justice.
So what about Word, after all?
I very much enjoyed these three talks, and in particular I was pleased that there was a robust comparison of Microsoft Word to two other more technical formats in front of a very techy audience. If you’ve ever heard me speak at a #techcomm event or read this blog for a while, you’ll know that like many of my peers I have a love-hate relationship with Microsoft Word. It’s a great tool for some jobs, and it’s terrible for others.
In my experience the usefulness of Word decreases as the length or complexity of the document you’re trying to write increases. In my current job, it’s the only authoring tool I need, as I rarely need to deal with a document more than 30 pages long, and I don’t use lots of graphics or any cross-referencing. I will readily admit that current editions of Word are orders of magnitude better than the versions we had 10 or more years ago, and like Richard, I acknowledge that 99% of Word users aren’t professionals (and that’s probably an underestimate). I have occasionally used this blog to advise non-professional users of some basic tips (here, for example).
Richard’s talk explained how it was possible to do really useful work with Word, but in doing so he was actually supporting an argument that I have made several times in the past. In comparison to other content authoring tools (and my counter example was usually Adobe FrameMaker) it is quite difficult to do complicated things with Word “out-of-the-box”. Once you have the skills to create your own macros and ribbons and templates, and when you have the management and IT cooperation necessary to lock down Word to only allow your templates, then you can make great strides, as Richard explained. But in my experience, even though some #techcomm professionals do have the skills to create the templates, very few of us are able to get the organisational cooperation needed to enforce them. So we are left with Word being widely and poorly used across an organisation, while tech writers are expected to publish faultless documents without the necessary support. Writing teams that ask for more are often told “but you have Word, what more do you need?” Imagine a Finance team asking for accounting software being told they already have Excel?