The failure of a Documentation Set is not typically due to writers not being able to write content. A set fails when the size of the set exceeds the writer’s ability to maintain the set in their mind and no tooling exists to manage the set for them. The only thing that keeps a large set of structured content from growing out of control is that the content was written as structured content in the first place.
What follows is a practical overview of how topics, maps, and reuse change the economic dynamics of a documentation project. This overview also explains where the costs lie for such a shift and when the shift may pay off within two to three release cycles.
Topics change what a writer is responsible for
So what exactly is a topic? Well, a topic is typically a self-contained chunk of text that is written to answer one question. This typically means writing a single chunk of text without reference to what comes before or after in a narrative.
But the biggest benefit of writing self-contained topics is that they can be reused in many different ways. A single procedure can be reviewed by a subject matter expert, translated by a translator, and linked to by a support engineer. All of this can be done without them having to read the surrounding chapters.
Typing topics is where the discipline comes from
Structured authoring to separate concept, task and reference. The constraint of typed topics for a procedure means that the procedure always has prerequisites, step-by-step instructions and a result. So a reviewer of a task can very easily see if any of the steps are missing, for example.
Maps separate sequence from substance
A map (often just a list of topics) contains only the references to the actual content, in a specific order. This enables the creation of an installation guide, a guide for the system administrator and even context sensitive on-line help, all created from the same set of topic-based content, covering different subsets of that content.
It makes large reorganization easy. You can move a 900-page document around in a matter of minutes, as opposed to weeks of cut-and-paste, with a high incidence of orphaned cross-references. A nested map of topics enables a single release author to work with a hierarchy of product-level maps written by subject matter experts, forming a single publication from the numerous components.
Conditional processing belongs in the map layer
Keep conditions shallow. A single topic with 6 overlapping conditions is harder to maintain than 2 separate topics. The break-even point for this type of reuse is much sooner than most people expect.
Reuse pays off, but only when it is governed
Reuse, Best Thing Since Sliced Bread, Worst Polluter of Good Content. Reuse of topics is one of the biggest advantages of structured authoring, but it also means that one bad move can cause masses of seemingly identical content to become tainted.
- Reuse at the topic level for anything procedural or conceptual that a reader would recognize as complete.
- Reuse at the fragment level, such as warnings, product names, and legal boilerplate, where wording is legally or commercially fixed.
- Avoid reuse where a passage merely looks similar. Coincidental similarity creates brittle dependencies.
- Require a where-used report before any edit to a shared component, and make that a gate in review, not a courtesy.
Consistent organization is a product of naming, not goodwill
Predictable file names and metadata (such as author and date of last modification) that are stored within a controlled vocabulary, and a structured file system that mirrors your information model, are critical components for large topic collections. If you are deciding how that model should look, it is worth grounding it in a proven standard such as DITA content structure rather than inventing conventions from scratch. Be sure to set up a good model for file names, metadata, and the file system that holds your topics before you hit the hundred mark. Retrospective setup of these issues will cost more than the original setup of your structured authoring.
Judging the investment by set size
| Set characteristics | Main benefit realized | Typical cost driver |
| Under 200 topics, single output | Limited, consistency only | Tooling and training outweigh gains |
| 500 to 2,000 topics, two or three outputs | Reuse and faster restructuring | Information model design and conversion |
| Multiple products, shared components | Component ownership across teams | Governance, where-used discipline |
| Any size with multilingual delivery | Translation cost scales with change, not volume | Vendor integration and segment hygiene |
Sequencing a migration
- Audit the existing set for genuine duplication, which establishes the realistic reuse ratio.
- Define the information model and metadata vocabulary with the people who will author against them.
- Convert one high-value, high-churn publication first and measure the update cycle against the old process.
- Expand only once the component governance process has survived a real release.
The one real question you need to answer about all this is, is the cost of the model recovered within two or three release cycles, where the main drivers are that your set is large, changing frequently, and needing to be delivered in numerous variants?
