A documentation team typically consists of many writers but only a handful of managers. Most difficulties stem not from the writers being too slow, but from the same sentence occurring in nine different locations, three of which may be incorrect. In DITA authoring this problem is tackled structurally, not procedurally.
Structure as a constraint, not a convention
A style guide tells authors how to write in a consistent manner. A DTD or schema for a document type makes inconsistent documents invalid. This basic difference between a style guide and a DTD or schema is the basis for everything that follows. Validation of documents against a DTD or schema enables editorial rules to be checked by the build process before the documents are published to readers.
Topic typing does the heavy lifting
In a DITA structure, information is organized into three main areas of content, concept, task, and reference. A single task topic typically includes an ordered sequence of steps with optional prerequisites and results. All of the background information can be placed in a separate concept topic, which does not need to be read before the task information. In this way, safety information cannot be buried in background information of a procedure.
Further restriction of the authoring choices (i.e. Allowed elements) within a topic type leads to another advantage, The output becomes so predictable that the styling can be restricted to a simple stylesheet, too.
Choosing the right reuse mechanism
Reuse is where so much management value is stored and where so much damage can occur. It is efficient to include a single warning in forty topics. But then someone needs to vary the wording of that warning for a single product line and before you know it that single warning has been edited in the single ‘source’ of that warning. How much flexibility does your current reuse method allow?
| Mechanism | Best used for | Maintenance cost |
| Topic reuse via maps | Whole procedures shared across deliverables | Low, provided topics are context free |
| Conref | Fixed blocks such as warnings and legal notices | Moderate, breaks if the source topic moves |
| Conkeyref | The same blocks when the source varies by product | Low at scale, higher setup through key definitions |
| Keyref for text and links | Product names, version numbers, UI labels | Very low, centralized in one map |
| Branch filtering | One map producing several variants | High if conditions are not governed |
A practical rule for deciding
Reuse the largest “Unit” possible, and only link to it indirectly if the content is going to change somewhere. Direct conrefs to a topic’s content are easy to write, but a real nightmare to undo, so use them only for content that will NEVER change (e.g. A glossary term definition).
Consistency that holds across releases
Terminology drift across large documentation sets is a slow failing problem. Tracking product names in keys makes it measurable, a product name change in one map will propagate to all maps using that key in the build process, not through some search and replace that fails to pick up all the occurrences in indexes and link text.
Conditions instead of forks
Conditional processing attributes enable the single source to be filtered to provide different views to different audiences. As with the names of attributes, the values of attributes must be controlled. Agree on a controlled vocabulary for a set of attributes and record that in a subject scheme map. Check that all occurrences of a given attribute have one of the values defined for that attribute in the subject scheme map.
Collaboration when writers are not the only contributors
Additionally, there are all sorts of people who use and translate your technical content (engineers, support techs, translators), and most prefer to work with your content in very different tools than writers do. Before inviting them in, it is worth grounding the whole team in DITA authoring fundamentals so everyone shares the same mental model of topics and maps. In DITA, topic granularity facilitates joint work by writers (for example, two people adding to adjacent steps in a procedure) in that their file edits do not conflict with each other.
What to put in place before scaling contributors
- A clear ownership model mapping topics to subject matter experts, stored as metadata rather than tribal knowledge.
- Review that happens on rendered output, with comments traced back to topic identifiers.
- A translation handoff keyed to changed topics only, so vendors quote on real delta rather than whole manuals.
- Automated validation in the build, catching broken keys and conrefs before a human sees them.
Scaling without adding writers proportionally
Furthermore, when the product line increases in size, the cost of a duplicate manual for a second hardware variant (that has 80% identical installation procedures) should not be anywhere near as much as the first manual. With maps, keys, and conditions, it isn’t.
Numbers worth tracking
- Reuse ratio, measured as unique topics against total topic references across all maps.
- Average topics changed per release, which indicates whether granularity matches your change patterns.
- Words sent for translation per release compared with total published words.
- Time from content freeze to published output, which exposes pipeline problems that writing speed cannot fix.
Thus, the degree of reuse that is achieved with a given model can also serve as an indicator of whether the model is being used correctly or not. If the degree of reuse continues to rise while the change in volume of content to be written remains constant, then this must mean that the individual units of content have been broken down into too small units of content and are now being assembled rather than written.
