We know that documentation will go stale in predictable ways. That means a product will change and three topics will be incorrect for some indeterminate period of time. More discipline from writers is rarely sufficient to prevent staleness of content. The writer’s work can be facilitated by tooling that makes visible the staleness of content and restricts the number of places that a single bit of information can reside.
I’ve listed these out in a certain order. They vary in cost to your process.
Structured authoring narrows the surface area for error
Structured authoring, or writing to a structure or schema, can help keep the content of topics consistent. The author writes to a DITA map, a DocBook XML document, or even to a custom XML or JSON schema. The key is that a procedure has prerequisites, steps are numbered, and there is a result. A reference topic does not accidentally morph into a tutorial.
The pay-off of having machine-checkable correctness is huge. It’s one thing to have a parser validate that the author has followed the structure of the document(s) they’ve written. But with Schematron rules, the structure of the document(s) can be used to check all sorts of business rules (e.g. That a safety warning has a severity attribute; that a step reference to a UI element also has a label attribute).
When lightweight markup is the better call
Of course, full XML authoring has its own overhead too. That’s best suited for teams publishing to a single output (e.g. HTML web help), with fewer than a few hundred topics, and no translation required. There are alternative approaches such as using Markdown or AsciiDoc within a docs-as-code environment (e.g. Within your application code repository). In particular, AsciiDoc is a more powerful markup language than Markdown, with native support for includes, attributes, and conditional content, all of which are very useful for content reuse.
Reuse mechanisms decide how much work an update costs
Duplicated sentences equal future inconsistencies. What reuse functionality do you need for the kind of duplication you have?
- Variables and attributes for volatile short strings, such as product names, version numbers, and port defaults.
- Transclusion or content references for shared paragraphs and procedures that must stay byte-identical across outputs.
- Conditional profiling for content that differs by audience, edition, or platform but shares most of its text.
- Generated content for anything that already exists in a machine-readable source, including API references, CLI help, and configuration schemas.
Content that can be generated should be prioritized for creation. For example, reference tables could be generated from an OpenAPI document or from code annotations. All hand-maintained inaccuracy can be removed from your inaccuracy problems by making this one decision.
Reuse has a review cost
This therefore does not necessarily mean that shared content is a problem, only that it must be tested with the review tool that the writers will use, to verify that the writer’s view of the unresolved output is the same as the reviewer’s view.
Choosing a toolchain against your actual constraints
The typical feature comparison for document tools fails to distinguish between enabled features and workable constraints on your team’s workflow. Translation volume, number of output documents, and reviewers’ technical capability to read markup all play a huge role. If reuse and multi-channel publishing are the binding constraints, it is worth evaluating dedicated technical writing tools before committing to a general-purpose editor.
| Approach | Best fit | Main cost | Reviewer requirement |
| Docs-as-code with Markdown or AsciiDoc | Developer-facing docs versioned with the product | Build pipeline maintenance | Comfort with pull requests |
| Component CMS with DITA | Multi-product, multi-output, heavy translation | License and schema governance | Web review interface |
| Cloud help authoring platform | Mixed writer skill levels, fast publishing | Export and lock-in risk | Minimal |
| Wiki or knowledge base | Internal process and policy content | Weak reuse and versioning | Minimal |
It is rare that a single tool will fit an organization’s needs for shared content. It is more typical that two will be used with clear bounds between them. The best test is to try to add a new topic and see if it can be written in both systems without problems.
Workflow automation that catches drift
These sorts of checks should run continuously as part of your normal tests for your code.
- Link and anchor validation on every build, including links into product UI and external standards.
- Terminology and style linting with Vale or an equivalent, using a vocabulary file your team owns.
- Snippet testing that compiles or executes code examples so a changed API fails the docs build.
- Screenshot age reporting that lists images older than an agreed threshold against a release.
- Ownership metadata and review dates stored in topic front matter, surfaced as a stale content report.
Connect documentation to the change that caused it
However, the best way to ensure this type of information is used accurately is as part of your process. In other words, create a procedure that ensures all issues that are labeled as being a behavior change also get documented. Then ensure your docs build in such a way that they are checked on the release branch (as part of your normal build process). This way you find out at the time of the change rather than 3 months later in a quarterly audit.
Maintaining the tooling itself
Schemas, variable lists and content validation rules, like any other written content, have a life cycle too. Assign someone to be the owner of the content model(s), review the variable lists for each release and remove unused condition definitions that no longer map to a shipping product. Also test the migration path to a new technical writing tool as thoroughly as you test the path to add content with export fidelity in mind.
Measure against something. Typically one would track the number of outdated documents and/or the number of documented defects found after a release. If after two release cycles the numbers for the above mentioned measures have not changed, then the problem is most likely with the workflow around the editor, not the editor themselves.
Read more : A Payroll Process That Grows With Your Small Business
