I once watched a technical writer search for the correct company name for a rebranded product for 45 minutes. The manual for this product was due the next morning and was part of a larger manual. After some digging, she found a PDF on a shared drive attached to a calendar invite buried within 3 email threads on a Confluence page. This was not a documentation problem but a systems problem and I watched her slowly come unglued.
The Good User Manual Creation Software Eliminates Confusion For Documentation Teams. Sorry to bang on about this again, but good user manual creation software is supposed to eliminate confusion and make life easier for documentation teams not introduce more confusion and make life a misery.
Why most documentation tools miss the point
The worst way to pick software is to treat picking software as if you were buying something. Read the description, download a demo, and then buy it because it looks good in the demo. People end up with what looks good to begin with and it does nothing to improve writing user manuals once they have it.
Most documentation tools are only written with the intention to store documentation. And then there is the lifecycle of a document after the first draft has been written. For example the 7th revision of a document 3 weeks after launch, because in the mean time the engineers changed a feature. Most documentation tools fail here.
Day to Day Use of Documentation Software
These are the things that really make a tool work so they get documented really well by writers, the people who can benefit most from a tool that makes writing documentation easier. None of the flashy exterior stuff. The plumbing.
- Single-source publishing, so the same content chunk can live in a web help file, a PDF, and a printed guide without being rewritten every time
- Conditional text that lets you swap content for different product versions or audiences without maintaining a separate file for each — because that way lies madness
- A variables system, so when the product name changes (again), you update it in one place and it propagates everywhere automatically
- Version control that doesn’t require a separate developer tool just to manage it sensibly
These are common, behind-the-scenes tasks that nobody typically acknowledges. However, without them, documentation processes will not be able to scale.
Structure and output: the balance nobody talks about enough
Following the development of documentation teams is fascinating. Almost all of them, who are working with structured authoring very early on, are more flexible in the long run than their colleagues. This is contrary to what one would expect, since more structure has to mean less flexibility for the writer. But it does not have to be this way.
Whether Technical Writers are authoring Procedures that will often need to be published in more than one place, i.e. in a full User Guide, in a Quick-Start card, and in an Online Knowledge Base. Managing updated content across multiple files is like playing blindfolded whack-a-mole, each hit updating one location while three others go out of sync before you can even save the change. In topic-based authoring software, however, each Procedure would be authored as a self-contained Topic. Whether published in a printed User Guide, on a Quick-Start card, or online in a Knowledge Base, the Procedure would look exactly the same in each case. A single change to the Procedure would thus update all occurrences of the Procedure instantly.
Tools that are based on a topic-oriented approach (such as DITA or another similar standard) enable authors to write content that is modulated, i.e. is suitable for distribution to a variety of contexts. This means that one and the same procedure can be very easily included in a full user manual as well as in a quick-start guide or in an online knowledge base. At first, working in this way can be quite tedious, however, once you and your team have “gotten used to it” it can be extremely painful to revert to the linear writing found in conventional word processing. Even writing long emails on a mobile phone, after months of working with a real keyboard, can suddenly become very tiresome.
Most documentation software is built around specific workflows or sets of workflows that match typical authoring processes. In practice, such software can look very different from one product to another.
A Quick Comparison
| Capability | Basic documentation tools | Dedicated manual creation software |
| Single-source publishing | Limited or manual workarounds | Built-in, often automated |
| Conditional content | Rarely supported natively | Core feature |
| Output formats | PDF, maybe HTML | PDF, HTML5, EPUB, mobile, print |
| Content reuse | Copy-paste | Snippets, variables, topic reuse |
| Collaboration and review | External tools required | Often integrated or tightly connected |
(There are large variances within the ‘dedicated’ category as well, some general publishing tools have invested greatly in certain features to become very effective in writing and managing documentation in a structured way).
The human side of the equation
Software can’t fix a bad process. Full stop.
Even the best tool for creating user manuals is completely powerless if the underlying process of creating documentation is already severely flawed. For me, one of the biggest challenges that writers and their managers face today is the fact that many teams produce inconsistent and outdated documentation. As a rule, this is due to a lack of clear ownership for the process of creating documentation, insufficient review cycles, and no clear rules for who is responsible for approving the finished documentation before it is published to customers. In such cases, the best documentation tool becomes nothing more than an expensive database for tracking all of the inconsistencies in the team’s documentation.
Effectiveness of documentation software is highly dependent on the effectiveness of the process in which the software is being used. This means that a team can have excellent documentation software, but still produce poor documentation if they have a poor process. This is because a team’s poor process will simply be transferred to the new software and become even more obvious because of the additional cost of the softwore.
There’s no elegant solution right now but I’d love to be proven wrong and until then I’ll stick with using the best tools to produce the best work and do my best to instill good writing practices and, above all, habit and discipline to avoid all the stress and hassle that will inevitably descend on us just when it seems to have all come together just in time for a launch.