By Niels Grundtvig Nielsen, Worldline
March 1, 2019

A lone technical author in a large company has to be persuasive, wily and diplomatic … or weep quietly in a corner as colleagues who’ve not actually been taught how to use a word-processor deliver almost unusable information. Well, that’s my take on it! though to be fair I was off to a good start here: during my interview with the then departmental manager and the technical author, it turned out they were already trying to introduce DITA-structured documentation. Also, most of my documentation tasks involve working with developers who are already familiar with the concept of re-use even if they’re astonished to discover you can apply the concept to text as well as code.

I started off by migrating some older documents, which was also a good moment for tidying up some of the content: a pre-emptive strike, if you like, that could also be sold as pro-active and show the document owners a technical author is more than just a typist with a spell-checker. After enjoyable discussions with individual colleagues, explaining to them how their content had been transformed and why, the time came where I was ready to give an in-house presentation. The rest of this article is based on that presentation, to give you an idea of how one author in one context negotiated the move to a new way of working. YMMD, but I wish you every success!

A Summary of the Presentation—Explaining Structured Documentation

I’m encouraged to see so many of you here! Today I’m going to give you a quick overview of structured documentation.

When I help you prepare a document, I apply the rules and principles of DITA – the A stands for Architecture. DITA guides authors in managing and re-using small chunks of information, which you then select and combine to build a longer or larger deliverable. It’s been an OASIS standard since 2005, and I was lucky enough to pick up many of the same rules from using IBM BookMaster in the late 1980s. Here’s how the unknown authors of the User’s Guide introduce this way of working:

You are about to learn a new way of creating and producing documents. If the documents you produce are simple, you won’t have to learn very much, despite the size of this book.

If you are used to using a typewriter or to using a word processor where what you see on the display screen is very close to what your printed document looks like (often called “WYSIWYG” for “What you see is what you get”), you will find that using BookMaster is very different.

The document you create on your screen does not look at all like the output document you print.

There are many reasons, with fancy names like “user productivity,” “document portability,” “device independence,” and even “text database” (with an occasional “long-term strategic goals” thrown in for good measure), for using the BookMaster method, also known as “Generalized Markup Language” (GML).

We’re not going to go into those reasons here; we’re just going to say that BookMaster is a powerhouse for complex and elegant documents, and for documents that will be updated frequently or over a long period of time. The beauty of it is that it also handles simple documents simply.

And, if we don’t have to concern ourselves with exactly how a document looks when we create it, this means that we have a document that is not locked in to always looking the same way for the rest of its life. (This is where the “long-term strategic goals” start to come into play.)

To take advantage of all this wonderfulness … IBM BookMaster, User’s Guide SC34-5009-05

I almost wish I’d written this User’s Guide; I’m certainly very grateful that I still have a copy, both for quoting from and for the ideas it deftly slips in. The jargon terms such as user productivity and long-term strategic goals are very persuasive, and the register that allows words like wonderfulness makes the document a pleasure to read.

The second reference I quoted to my audience, before I came out of my corner and started using my own words, referred to the results of a survey. One of the questions was What makes developers unhappy, at least at work? The top two answers were unrealistic expectations and poor documentation. I glossed these as a single item being expected to write documentation and got a grin of recognition from the audience. And then I said

Over the centuries, we’ve become accustomed to larger and larger documents. Over the last twenty years, we’ve also become accustomed to larger and larger executables. Both of them become easier to manage when we break them down into smaller, consistent components – a familiar idea for code, still an innovative idea for documentation.

Imagine an exploded copy of a manual where every paragraph was written on a separate index card, I continued, including classification information making it easy to sort, select and re-arrange the cards. Then replace the stack of index cards with plain-text topic files and meta-data. The audience was still with me, so I touched on the advantages of rules: it’s easier to document a single task if you have a structure saying “this is what you (may) need to say and in this order”, for instance, and it’s easier to produce consistent information about a set of tasks when you can apply the same structure to all of them. This idea is actually reassuring, because when you have rules and validation you can be more confident about … re-use! and I mentioned three familiar contexts from our environment:

  • in documents—if six terminals have the same power-supply, I can write the description once and include it in six manuals
  • in topics—if twelve related tasks have three steps in common or the same prerequisites … same thing! I can re-use these elements
  • in text—use variables and save even more effort The power-supply for your {$productName} is completely eco-friendly

Statistics can often back up an argument, so I gave a real-life example of a set of installation procedures: ten documents, 230 sections if you check all the tables of contents, but only 85 unique topics to manage and keep up to date.

Extra benefits

Without committing myself in too much detail, I then went on to mention branching, or “flow control for documents”:

IF {deliverable for product A} THEN {include topics tagged product=A}
IF {content status='new'} AND {revision=[latest]} THEN {highlight in output}

This felt like nearly enough information for a first session, but I did briefly touch on two more benefits: versioning / RACI information inside every source file, and guided editing plus validation. These underline the idea of treating documentation content as rigorously as code: more reassurance for my audience!

Real-life examples – what I show is what you get

The second half of the presentation was based on examples, screenshots of a concept topic, a task topic and a reference topic both in the IDE and in one of the possible output formats, plus a word about .ditamap containers. Of course, this was also the moment to show them the same source files could be deliver A4 .pdf and Web help: they liked that! And to mention that the developer team who package the Web help into the customer deliverable have helped me store the source files in a git repository – as soon as I commit agreed changes, this triggers generation of an updated Help set.

Better documentation from teamwork

So now I’m working with colleagues who understand about reuse and structure! as a bonus, they are also adopting effective commenting now they get .pdf files to review. No-one had ever explained to them that (for instance) you don’t need to use one tool to draw a strike-through line and then another tool to show the text you want to add instead. The documentation review and update process is generally that bit tighter than it used to be, and being able to focus on bite-sized topics saves the developers time and effort they can now use on … development.

That’s where the division of labour from the title comes in. As for DITA, colleagues now understand why I say:

  • Lots of people I’ve spoken to about structured documentation are afraid of it.
  • They think it’s a strait-jacket, a limitation.
  • This just isn’t true. It’s a powered exoskeleton, helping you get more done