Many documentation teams come to realize the value of topic-based authoring the hard way, it takes longer than expected to document a feature (three days instead of one hour) because so many different documents (user guide, administrator’s manual, training manual, knowledge base) are affected by the same process. Besides the primary benefit of reuse, there are many other benefits for review, translation, search and even writing itself.
Smaller units change how work is estimated and assigned
As you start to write product documentation as topics, as opposed to chapters in a long document, you can now complete, review and release individual topics as opposed to entire documents. The amount of content that needs to be written to complete a deliverable is greatly reduced as a result of this approach.
With topic-based authoring, the end of the reign of terror of a single writer for a large manual is near. When three people are writing the same deliverable, each of them can work on different files. Merge conflicts in version-managed files become a rare exception.
Making topic granularity a deliberate decision
The granularity of individual topics is a big problem for most authoring approaches, too granular, and there are hundreds of tiny pieces of text no one can ever find again; too large, and you’re back to the problem you were trying to solve in the first place, managing one very large document. In topic-based authoring, a topic is a piece of content that answers one question for one audience and can then be reused without being edited.
- Concept topics explain what something is and why it matters, with no steps.
- Task topics contain a single procedure, ideally under twelve steps.
- Reference topics hold structured data such as parameters, error codes, or field definitions.
- Anything that mixes two of these is a candidate for splitting.
Reuse that cuts maintenance cost, not just word count
Saves volume of related content, not just bulk of the same information. A single safety warning, a single login procedure, a single list of system requirements for different products are written once and then used in twenty places. All twenty documents are updated correctly every time.
The same also applies for the conditions for the written content, like for the audiences, for the versions or for the output channels. The more conditions you have for your written content, the more complex the testing for it gets. So keep them small, well-organized and document them. Additionally, check for unused conditions from time to time.
Where reuse stops paying
Note that not all content should be reused. Marketing overview documents for example, Release Notes and mostly narrative based documents do not read well when reassembled from their original source. Procedural, factual and especially regulatory content however is perfect to reuse.
Translation and localization economics
Another major advantage of topic-based documentation is that it reduces the amount of words in your documentation greatly, which in turn is how translation of documentation is charged for. The Translation Memory System will then find all the changes made in a topic, and only those parts will be translated by a human translator.
| Workflow stage | Monolithic document | Topic-based source |
| Change identification | Manual diff of full chapters | File-level change list from version control |
| Content sent to vendor | Whole document, often re-exported | Only modified topics |
| Review scope | Entire deliverable re-read | Changed topics plus affected assemblies |
| Risk of orphaned content | Low visibility until publication | Detectable by link and reference validation |
Better fit with how readers actually search
The single page within a manual that a reader most often encounters in the middle of a manual needs to be able to stand on its own. This is why a single topic is comprised of a title, a description of the prerequisites for that information and cross references to additional, related information.
Even for in-product help like chat support surfaces, the biggest benefit of topic-based authored content is search. The topics therefore need to have meaningful metadata, so that the information found by the search can be presented within a suitable context. If you are choosing a tool for this, topic-based authoring in MadCap Flare is worth evaluating, since its metadata and conditional tagging carry straight through into search results across every output you publish.
Metadata that earns its keep
- Assign a content type to every topic so filters and templates can act on it.
- Record product and version applicability rather than embedding it in prose.
- Track an owner and a last-verified date to drive content audits.
- Avoid free-text keyword fields, which drift and go unmaintained.
Reviewing and governing a topic library
In terms of tracking, single-sourcing topics are highly efficient. You can track how long it has been since a release was made to a particular topic. You can also track the frequency with which the reusable pieces of content (snippets) are used. Finally, tracking conditions that are no longer valid is also efficient.
Identify each topic or piece of content within your files in such a way that an audit of these items on a quarterly basis is straightforward. This audit can be used to delete unused topics, to merge near-identical copies of topics and to check how pieces of reusable content are used in all contexts and whether they still read correctly there.
