The time a documentation team spends writing content is usually greatly overstated. What eats up most of their time is dealing with different versions of content, trying to find the last approved version of content, dealing with broken outputs caused by changes to templates, and trying to figure out whether or not outdated procedures still apply to current releases of products. The authoring features in a documentation tool that are most valuable are those that eliminate these problems rather than making individual topics look better.
What follows is a more in-depth explanation of all the features you should look for when evaluating a documentation tool, the trade-offs you have to make for each, and how you can test if your current setup already meets those requirements.
Structured authoring that enforces consistency without constant policing
Structured content pays off when the system is set up in a way that the structure is enforced by the schema (or template) rather than by commented out text in the review comments. A procedure without a result statement is rejected just as much as a heading level that skips a tier is flagged. All this can cost an editor’s time and a round trip in the worst case.
You can test this by having a new contributor write a new compliant topic. If onboarding the contributor to writing new documentation requires reading a style guide, then all you have is structure on paper.
Topic granularity decisions
Within any structured content system, granularity of content is the most critical decision, too large a chunk of content is often impossible to reuse; too small a chunk creates a huge number of documents that result in a massive file system and poor navigation. In general, it is best to split content at a point where a search for that content would result in a single, decent-sized document that contains sufficient information to take action.
- One task per topic, with prerequisites stated rather than assumed.
- Conceptual background separated out so it can precede several tasks.
- Reference material such as parameter tables kept standalone and linked, never duplicated inline.
Reuse mechanisms and the maintenance burden they carry
It is tempting to think that reuse of content is a way to cut word count. But once written, the biggest advantage of reuse is that a single change can propagate to all instances of the reused content. This advantage is biggest for items such as safety notices, legal wording, and product names that have changed as a result of a rebrand. Each method of reuse has a cost to maintain, and mixing them up results in content that cannot be written with confidence.
| Mechanism | Best used for | Main trade-off |
| Variables | Product names, version numbers, URLs | Breaks grammar if the replacement text changes length or gender in translation |
| Snippets or content references | Repeated warnings, shared steps, boilerplate | Edits in one place can surprise authors of another deliverable |
| Conditional text | Audience, platform, or edition variants | Condition combinations multiply fast and become untestable |
| Topic level reuse | Whole procedures shared across manuals | Requires discipline in cross references and context setting |
Keeping conditions under control
Limit the number of condition tags in the earliest phases of the system and make sure that everyone knows what each of them means. Audit unused condition tags for major releases and make sure that the number of valid builds that have to be tested is never greater than what your team can realistically accomplish.
Single sourcing and output control
Single sourcing has value only if you can still control the individual outputs. In other words, distributing the same content to a web help site, PDF, and in-product help panel is only efficient if each output can be styled and filtered as desired without having to create a completely new source for that output. If that is the model you want, it is worth looking at the MadCap Flare technical writing tool, which separates content from presentation so an author can shape each individual output through a stylesheet or a target.
Be wary of general document publishing tools when it comes to items like page breaks, running headers for print output, collapsible sections for web output, and others. Try to test all features, especially the “nasty cases,” first.
Workflow features that keep documentation aligned with the product
Documenting a product that is outside the author’s normal working environment, in terms of release cycles, creates drift from the product. However, being able to integrate with version control software, create new branches for releases, and even compare the source of two different versions of a topic is key. As for reviews, being able to add reviews without requiring a license and without requiring the author to learn the authoring environment is key.
- Branch documentation alongside the code branch so unreleased content stays out of published output.
- Tie topics to issue identifiers, which makes it possible to confirm coverage before a release.
- Automate builds so broken links, missing images, and failed conditions surface immediately.
- Keep review cycles short and scoped to changed topics rather than whole manuals.
Measuring whether the workflow works
Track the time it takes to incorporate a change to a product into the documentation, and the number of topics changed in a release. The former provides insight into your current authoring efficiency; the latter into the efficiency gain of switching to a new set of tools and/or headcount.