At a certain point in a documentation team’s evolution, the cost of maintaining existing content can exceed that of creating new content. As a product line evolves into various product variants, new safety warnings are required due to changes in regulation, and a brand refresh is undertaken, the work of a writer shifts from creating content to hunting for existing information. That is the purpose of structured authoring, to change the arithmetic.
Structured writing separates meaning from presentation
This content is written into defined component types, which are structured according to enforced rules. For example, a procedure has a context, prerequisites, steps (numbered), and a result. A reference topic might contain tables of properties. The authoring tool then prevents the task from devolving into a confusing mixture of narrative and instruction by not allowing content that breaks the model.
At the time of creation of content, the writer applies formatting only in so far as he wants to identify a block of text as a warning (e.g. Because it contains actions of exceptional importance). The remaining formatting is then applied by stylesheets and transformations at a later time.
Why constraint improves output
At first, teams resist the loss of flexibility in their content creation process. But once they’ve got used to it, they realize that all the low-value decisions that they previously had to make about their content have been taken away from them. So, instead of spending their time arguing about whether a particular procedure would benefit from a brief summary at the start, they can focus on the real issues in the content, the technical accuracy and so on.
Consistency becomes a property of the system
A large portion of the content in a style guide can be translated into restrictions that can be enforced by a structured authoring environment. Hence, element order, mandatory metadata, nesting restrictions and term checks can all be implemented at the authoring stage, eliminating the need for reviewers to recall these aspects of the style guide.
Structured authoring has a compounding effect on large teams. A writer new to a project with a large corpus of already written content in the same structured environment can very quickly start writing in the correct style. On-boarding cost is reduced significantly, and the normal variance in human written content that causes problems with translation memory is reduced to almost nothing.
Consistency that translation vendors can price
Any change in the source content that doesn’t correspond to a change in the product will incur charges from the localization vendors. However, this content will translate very efficiently, typically higher segment matching rates, and hence save a lot of cost in each language, especially when dealing with many languages (10+). The savings usually outweigh the initial investment.
Reusable content changes what a correction costs
Reuse, copied and (slightly) adapted content, is often cited as one of the benefits of structured authoring. However, many organizations experience the opposite, even though content is stored in one place, in reality it is copied from one manual to another and adapted there. This in turn can create a new maintenance nightmare in the new toolchain.
Useful reuse patterns include the following.
- Warnings, legal notices, and compliance statements held once and referenced everywhere they appear.
- Shared procedures across product variants, with conditional elements for the differences.
- Specification tables generated or imported from engineering data rather than retyped.
- Variable text for product names, model numbers, and units resolved at publication.
Reuse content only where the meaning is identical in all contexts in which you need to use it. Use conditions, or even separate components, for content that looks similar but is not identical in meaning. Reuse such content only after you have adapted it to the needs of each context and it reads naturally in each case, do not force reuse of content that looks almost identical but is not.
Version management at component level
Document-level versioning informs you that a manual has changed, whereas component-level versioning not only informs you that a manual has changed but also tells you which step in which procedure has changed. It shows you when changes have been made and by whom. Impact analysis can then be carried out using queries instead of laborious investigations.
Branching for product releases
When content is structured in a meaningful way, it can also be branched and managed to follow the release of software or hardware. It can then be merged when the relevant versions have converged. Structured authoring thus mirrors the way that development works and enables documentation to be released on time to follow the releases of software, etc.
Multichannel publishing from one source
With content as structured semantic content, all outputs, printed, online Help, in-product information and even data feeds for chatbots, are generated by transformations from this same content. One set of content components is turned into different outputs by style sheets and transformations, and a mature help authoring platform built for technical documentation is usually the most dependable way to manage those transformations, with each output being generated according to the requirements of that channel.
| Approach | Cost of a content change | Output channels | Best suited to |
| Desktop publishing files | Manual edit per document | One, with manual export | Small, stable product sets |
| Web CMS pages | Edit per page | Web, limited print | Marketing-led content |
| Structured component store | Single edit, propagated | Print, web, in-product, API | Multi-variant, multi-language portfolios |
Deciding whether the investment fits
Structured authoring is only worth the investment for large volumes of content that will be reused again and again, in variants, in languages, for audit purposes. It is rarely worth the investment for short documents that will only be published in one language and will rarely need to be changed. Ultimately, you must determine whether or not the structured authoring model you choose will pay for itself within 6-12 months, through reductions in rework, in additional first time content.
- How much content is duplicated across your current outputs, measured rather than estimated.
- How many channels you are expected to support within two years.
- Whether your subject matter experts can work within a constrained authoring interface.
If all the above points are essentially saying the same thing, then yes, structured authoring will start to pay off soon, in terms of avoiding a lot of rework, not in terms of writing things faster in the first place.
