While the ability to write documentation sets does not fail as frequently as one might expect, the content within them often fails to have formed in a manner to make change easy to manage, particularly for translation. Thus, such content can lead to increasing costs for each subsequent translation cycle and numerous questions regarding content that exists in print but which cannot be found, all answered by the content having formed in a structured manner.
There are a number of mechanisms to reduce effort, but also to move work from one place to another. Each of them carries a weight and has trade-offs to consider.
Constrain the model before you constrain the writers
Content models that let you write anything will get used for everything in a year or less. That’s why the useful constraint isn’t a style guide, but rather a schema that prevents users from saving bad content in the first place, using tools like DITA, a custom XSD, or even a strict JSON schema behind a form-based editor.
Start with the core information types that will form the bulk of your documentation set. Most technical documentation is comprised of 3-4 information types, concept, task, reference, and troubleshooting. It’s only when you find that one of your existing information types causes you to document something in an awkward way that you consider adding a fifth information type.
Decide what metadata is mandatory on day one
There is considerable cost in retrofitting metadata. So ensure that key product, audience, lifecycle status and output channel metadata are mandatory. The rest of the metadata is optional and should generally be avoided as it is prone to become noise that no one trusts.
Reuse that survives contact with a release cycle
While copy-paste reuse of small portions of content is easiest of all, initially, it has large negative effects down the line. If content is written as structured re-usable units from the outset, there is cost for setting up the structure but later huge returns on each subsequent change to the content.
Three reuse mechanisms cover most real needs
- Topic-level reuse, where a complete unit appears in several publications. Best for installation steps, safety notices, and shared reference tables.
- Fragment reuse through keys or variables, where product names, version numbers, and URLs resolve at build time. This removes the most common source of stale content.
- Conditional filtering, where one source serves multiple audiences or editions through profiling attributes. It is powerful and the easiest of the three to overuse.
Set a ceiling on conditional complexity
However, the conditions for a document multiply quickly. As an example, a document with four independent attributes can have as many as 16 different versions of a single document. It’s rare for a team to be able to monitor all of the different versions of a single document. Set a maximum number of conditions for a topic and track which of those conditions are published. Use the number of conditions greater than the maximum as an indicator that a document should be split.
Match the storage approach to the size of the problem
The need for a full CCMS is also dependent on volume, translation and users interacting with the content.
| Approach | Works well when | Main cost |
| Files in version control | Under a few hundred topics, one language, writers comfortable with branching | No reuse reporting, manual link management |
| Headless CMS with schema validation | Mixed web and product content, moderate reuse, API-driven delivery | Weak support for conditional publishing and translation memory |
| Dedicated component system | Thousands of topics, multiple languages, regulated review trails | Licensing, migration effort, specialist administration |
Where there is a high volume of content to be translated, and that content is also reused in many different deliverables, CCMS software is worth considering because it tracks changes to the content throughout the translation process. It enables only the changes to be translated in subsequent updates.
Workflows that create evidence, not just approvals
Finally, record that a reviewer approved a piece of content. An email that states the content looks fine today is of no value six months later when some auditor asks who approved that procedure.
To achieve this, keep the number of states in your workflow small. For most purposes, Draft, In Review, Approved and Retired are sufficient. Each additional state provides a further opportunity for content to be lost.
Automate the checks a human should not be doing
Build-time validation tests for broken hyperlinks, unresolved references, missing alternate text for images, orphans, and incorrect usage of terms. It should fail the build instead of logging a message. This way reviewers can focus on checking for accuracy and proper expression instead of things that a script can check for them.
Measure the things that predict trouble
These are ‘operational metrics’ which should be measured and reviewed on a quarterly basis and which indicate where action is required
- Percentage of topics unchanged for longer than two release cycles, which flags likely stale content.
- Reuse ratio, meaning unique source topics divided by total published topics.
- Average age of content awaiting review, broken down by owner.
- Words sent to translation per release, compared against total word count.
Measuring these metrics on a quarterly basis enables developers and documentation authors to make a number of key interventions. A rise in translation spend against a rise in content (i.e. No growth in reuse) suggests that conditions on a topic have spread and it needs to be split. A fall in reuse means authors are currently finding ways to work around the documentation structure and a mechanism to track this is needed.
