Structured content standards like DITA, S1000D, or a constrained DocBook profile have a poor adoption rate among documentation teams because they look elegant. In reality, they are adopted because unstructured content has a natural breakpoint where it can no longer scale, when a product line splits, when a second language is added, or when support of the same content in a help center, as PDF, and in product features like wysiwyg-editable support fails.
What returns will you get from that investment and what trade-offs are you going to have to make? Does it match the work that your team does today as opposed to three years from now?
Consistency stops being a review problem and becomes a system property
In unstructured authoring, consistency is enforced by people. So someone reads through the work in progress and notices that in one task the customer reference number is called a “customer reference number” and in another that it is called a “client ID”. They file a comment against the difference. That works for 20 documents but not for 2,000.
Standards like DITA, S1000D or a restricted version of DocBook shift part of the burden to the schema. The only thing that is left for the author is to enter the content for the task topic. Since the task topic requires a context element, prerequisites and stepwise numbered actions for example, the produced procedures will look alike because they cannot be written differently.
What the schema cannot do
Structure dictates form, not content. It does not and cannot check for matters of importance to humans reading the resulting published content. In particular, all attempts to enforce terminology control require a managed glossary; and, for maximum effect, a linting layer which checks all authored content against said controlled terminology.
Reuse works when the content was written to be reused
Reuse is often the biggest “selling point” for content management systems, but is most often poorly implemented (reusing trivial “facts” such as product names in different flavors, conditional copy, etc.).
Content that has real reuse in it typically has a number of characteristics in common.
- It is self-contained and does not refer to “the previous section” or “as described above.”
- Variable elements, for example product names, version numbers, and UI labels, are held in keys rather than typed inline.
- It sits at a sensible granularity, typically a whole topic or a complete warning block, not a half sentence.
- It has a named owner, so a change can be approved by someone accountable for every place it appears.
Measuring it honestly
Look to see how much of the deliverable is actually derived from other topics. Then track the reuse as a percentage and report the number of source topics for each output that has high reuse. A high reuse # with constant authoring is a great metric to report upward. A high reuse # that is based on reuse of trivial fragments is not useful.
Localization economics change the calculation entirely
Structured content is mostly a quality / efficiency argument for single language teams. As soon as you add translation to that mix, the argument becomes a pure cost argument with numbers.
Segment-level change detection, Rather than shipping the entire document to vendors for localization, only the modified topics are sent. Translation memory matches improve because the boundaries of sentences and the markup are fixed across versions. Much of the layout work is also eliminated because the content is generated rather than reflowed for different languages. If translation volume is what drives your budget, it is worth understanding DITA for technical documentation before committing to a schema, since its topic boundaries map cleanly onto how vendors price incremental work.
| Activity | Unstructured workflow | Structured workflow |
| Scoping an update | Manual diff of full documents | Automated list of changed topics |
| Translation volume | Whole files resent, partial memory match | Changed topics only, high memory match |
| Formatting per language | Repeated DTP for each locale | Generated from a single stylesheet set |
| Terminology control | Vendor glossary, applied inconsistently | Keys and termbase enforced at source |
| Dominant cost driver | Page count | Word delta since last release |
Multichannel publishing is a separation problem, not a tooling problem
The standard way that many documentation teams purchase a publishing engine is with the false assumption that this will automatically provide them with channel flexibility. The reality is that all formatting decisions are embedded in the source, so that bold text in the source has come to mean ‘this is a UI element’, tables have been used to lay out content instead of to store tabular data, and the levels of heading have been used to force page breaks.
By marking up content to the UI label, for example, you can get the HTML renderer to render it one way for online help and another for PDFs, while also allowing retrieval by chatbots and aiding content to be made search-indexable and retrieval-augmentable.
Sequencing the move
- Audit existing content and discard what nobody reads before converting anything.
- Define a constrained specialization rather than adopting a full standard unaltered.
- Convert one high-churn, multi-locale product line first and publish real outputs from it.
- Build the metadata model and reuse library from what that pilot reveals.
- Expand only once authors can work without daily support from the tools owner.
When the investment is not justified
While there are many costs associated with implementing a structured content solution (e.g. Cost of tools, schema design and maintenance, author training, etc.), these costs are often not realized by small teams (less than 10 people) who are only producing a single language deliverable for a single, stable product. Below the threshold of two or more of the following (multiple languages, multiple channels, multiple products, regulated content), good old-fashioned templates and style guides go a long way in creating quality content with minimal additional effort.
