What is a single source of truth?
Often a company’s product information is scattered all over the place. The same information is created, managed, reviewed, approved, and translated in different departments and teams. Uncertainties can soon arise if information is being supplied from different sources. Which is the latest version? Where has a spelling mistake been corrected and where not? Which information has been checked for technical accuracy? The upshot? The information is redundant and sometimes even inconsistent, it takes an enormous amount of effort to manage it, and it’s highly susceptible to errors.
To avoid uncertainties like these, a single source of truth needs to be defined. This is a central data repository for all content in which the status of the content can be ascertained immediately (e.g., approved, versioned, obsolete).
Why a single source of truth is important for technical documentation
Technical writers are responsible for collecting all relevant information and keeping it up to date at all times. This ensures that the product documentation only ever contains current, complete, and reliable information for users. The less redundant information floating around, the more efficient and cheaper it is to create technical documentation. That’s why the technical writing department is the obvious data hub and therefore the single source of truth for businesses.
The advantages of a single source of truth in technical documentation
There are many benefits to technical writing departments collecting and managing content in one data source:
- Re-using content saves time when creating new documentation.
- Publications are ready faster.
- Redundant information no longer needs to be managed.
- Lower localization costs as content is only ever translated once.
- Susceptibility to errors decreases while text quality increases.
- Customers and service technicians receive reliable, up-to-date information, which boosts product safety and satisfaction.
From a single source of truth to single-source publishing
There’s another advantage to having a single source of truth too: if all data is stored centrally in a single repository, content can be compiled from modules and published in various layouts and on different output channels. This is known as single-source publishing.
The benefits of single-source publishing:
- Identical, up-to-date content appears in every publication, regardless of whether in a printed manual, as online instructions, or information in an app.
- Changes only need to be made in the central data source. Text modules are then automatically changed wherever they are being used, resulting in consistent, up-to-date information across all channels.
- Layout templates and automated workflows enable content from the central repository to be output in the required publication format, putting an end to time-consuming formatting work.
One source – many formats: how does it work?
To create technical documentation according to the single-source principle, you need to use specific authoring techniques. It all boils down to three things: modularization, multichannel capability (media neutrality), and automation. Let's take a look at each of these in turn to see which aspects of single source produce which changes in writing habits.
1. Modularization
The core principle underpinning every content management system is to break down the text into smaller, reusable units. This is known as modularization. The objective is to only create these units once, and then to use them in different contexts as often as possible. The same warning notice is simultaneously part of a procedure, it then appears again as part of the section on safety and, last but not least, it also appears on a sticker on the machine.
The right size of information unit
The problem is that the smaller the units, the higher the workload involved in reusing them. Very large units, on the other hand, can hardly ever be used more than once. The ideal module size depends on a whole range of individual factors. Sometimes, meaningful modules are very small, consisting of just a single sentence, but in most cases a manageable size is two to three paragraphs. Occasionally, modules may even be complete chapters, as with the warranty information in a manual.
Pay attention to references in the text
Beside the question of how large the modules should be, modularization places another requirement on technical writing. The sentences in passages of text often refer back to each other without us even noticing. But every “it” and every “therefore” links back to something mentioned earlier in the text (as does every “but”, by the way). Words like these weave a dense web of relationships that bind the text as a whole together.
It’s therefore very important when formulating modular text units not to refer to text that might not even exist in the final version of the document. Modules must be self-contained and only in very rare cases (e.g., explicit links) reference other text strings.
2. Media neutrality
The information in a content management system should be reused as often as possible. What this means in practice is that content must be equally suitable for a printed manual as for a website, a documentation app, or as a content element in an augmented reality application. Modular content management creates a basis for this, but is in itself insufficient, as texts also contain many terms that are media-specific: “page“, “link“, “footnote“, “click“, “chapter“ – the list goes on.
In single-source writing, terms like these must first be identified. Only then can the technical writers decide whether the terms can be avoided, which is the best option if there is any doubt. In the few instances where this is not possible, the respective media-specific term can be stored in a variable in a CCMS and then replaced during the production process with one appropriate for the media in question.
Tip: Include media-specific terms as stop words in the terminology databases used by technical writers to warn the authors whenever they use such a term.
3. Automation
Single-source publishing means rapid dissemination across various media channels and short update cycles for information products. Publications can even be created with ease from large content databases if the workflows are mostly automated – both when collating the content and designing the layout.
The key to this is to carefully select the metadata that will control the automation process. This means that single-source writing involves not just the authoring of the content, it also relies on correct tagging with various items of metadata. You can use ST4 AI Jetpack (a plug-in solution for the ST4 content management system) to automate this task too.
