How can organizations keep technical content consistent?
Content mechanisms are the source structure, content reuse, the review process and measurement.
Diagnose the type of inconsistency before choosing a fix
All inconsistencies are not caused by the same problems and thus solving the problems for consistency will require different solutions than what most teams purchase for “content management”. Separating out the different modes of failure helps to identify the correct solution.
Drift occurs when a shared instruction is duplicated in several places and only some copies are updated. The fix is reuse, not style guidance.
Divergence occurs when writers describe the same concept differently because no agreed term exists. The fix is terminology governance.
Structural variance occurs when similar topics are organized differently, so readers cannot predict where information sits. The fix is a constrained authoring model.
Stale ownership occurs when nobody is accountable for a content area after a reorganization. The fix is workflow, not technology.
Run a sampling audit, not a full inventory
A simple content inventory of 20-30 key topics across key areas in high volume support is likely to reveal where to start with consistency fixes within the first few weeks. Classify each defect as structure, content, browsing or workflow. Prioritize based on that classification.
Use structured authoring to make the correct pattern the easy one
Structured authoring removes decisions from the authoring process rather than documenting them for the reviewer to check. A task topic with a context, prerequisites and steps to be completed in a particular order ensures that writers write content in a particular sequence and reviewers check for consistency rather than discovering inconsistencies in a mess of text.
A typical misstep in implementing a metadata standard (e.g. DITA) is to enable the full range of optional elements, thus ending up creating constraints which in turn need to be described in a style guide to achieve the desired level of consistency. Instead, turn the standard on its head and start by defining constraints, i.e. Which of the available elements are actually enabled for your writers, and where within a topic’s structure they are permitted to appear. Limit admonitions to the 3-4 that really make sense in the domain at hand.
Keep the authoring interface aligned with the model
Displaying the constraints of the valid document in the way writers work, such as using templates for topics, and checking for constraints such as missing required elements, while the writer is still writing, not at build time, is much more effective than simply displaying a blank page and telling writers to work within the constraints of the valid document.
Design reuse around maintenance cost, not elegance
Content reuse also trades off between document authoring and later management. Thus, reuse of content needs to be weighed against how often the underlying content will change, and against how many deliverables rely on the same reuse of content. Teams facing those trade-offs are usually best served by a component content management system, which offers several different reuse mechanisms, each failing in different ways.
| Mechanism | Best suited to | Maintenance cost | Typical failure |
|---|---|---|---|
| Variables and keys | Product names, versions, UI labels | Low | Grammar breaks when values vary in length or gender |
| Fragment reuse | Warnings, shared steps, legal text | Medium | Edits made for one context break another silently |
| Whole topic reuse | Procedures identical across products | Low per use, high to change | Topics forked rather than conditioned |
| Conditional profiling | Variants differing by audience or platform | High | Condition sprawl makes output untestable |
Set a reuse threshold and record intent
A good rule of thumb for a CCM environment is to reuse content that is shared by three or more deliverables. Duplicate content that is shared by two deliverables and review those on a quarterly basis. Keep track of why a given fragment of text exists in metadata for that fragment.
Build consistency checks into the workflow
Reviewing for inconsistencies will naturally miss things that a reviewer happens to notice whereas automated checking of the same type of inconsistency will identify it every time it occurs.
-
Validate structure on commit so invalid topics never reach review.
-
Run terminology and style rules against a maintained term list, blocking deprecated terms and flagging unapproved synonyms.
-
Check link and key resolution across all output variants, not only the default build.
-
Reserve human review for technical accuracy and clarity, the two things tooling cannot assess.
Assign a single owner per content area
Shared ownership of content leads to inconsistent decisions. Designating one person accountable for each of the major areas of content (task topics, for example) is necessary. That person must approve changes to terminology and reject structural changes that are contrary to their own decisions. The assignment of accountability for areas of content must be revisited after major reorganizations of the team.
Measure the result in operational terms
This data needs to be compared with editorial opinion (e.g. The number of editorial hours expended per feature set), however good the editorial team is, numbers are better than opinions.
