Documentation teams typically deliver content to many outlets (web help portal, PDF for procurement, in-product help, knowledge base articles that are pasted into tickets by support agents, etc.). Getting the initial content delivered is rarely a challenge. But, sustaining 6 outlets (for example) through subsequent product changes on Thursday afternoons is a real challenge.
What is working for us as documentation for a product release is a single-sourcing approach for all channels to be published off of one source. We describe in detail how we structure our content, where we see a big added value in reuse, and how we decide for each channel whether it needs to be published as a separate output or not.
Separate the content from its destination
Publishing to multiple channels fails if one writes with the primary goal of being published on some specific output. A paragraph written for printing a manual will assume a specific reading order (i.e., starting from the front of the book) and thus will fail to be useful when read by someone who arrived at the information in the middle of a search result list of help topics.
Each topic of content needs to be written in such a way that it can be read in isolation. So instead of writing a lengthy chapter for example, write a number of short self-contained topics that can be read in any order and reconstructed into different outputs of content.
Practical rules for topic boundaries
- One procedure per topic, with the conditions for starting it stated explicitly.
- No cross-references phrased as “above” or “on the next page,” since those break in any non-linear output.
- Conceptual background separated from steps, so a condensed output can take the steps alone.
- Screenshots and callouts tagged by channel, because an in-product panel rarely has room for a full-width image.
Build reuse where variation is predictable
Much is made of the benefits of reuse. But all reused fragments are in some way dependencies that need to be remembered by someone. The test of a good reuse is whether the same text needs to be identical on all occasions that it is used, or whether it just looks similar today. Safety warnings, legal boilerplate, product names, and supported versions are good examples of things that rarely change and need to change everywhere. Narrative explanation is rarely a good candidate for reuse because it is easily tuned for the local circumstances.
Variables are usually used for short strings like product names which are going to be changed in the near future. Other variables will be used for legal boilerplate, supported versions, safety information, and for installation information. The majority of narrative explanation is unique to a single context and is better left to be explained in that single context.
Variables, snippets, and conditions
First, we have Variables that store short strings (e.g. Product names that get renamed). Then we have Snippets that hold bigger chunks, like paragraphs or tables, which are then included in various topics. And last but not least, there are Conditions that determine whether content is shown or hidden based on the output being generated.
They multiply quickly and should be kept as shallow as possible. Name tags based on the audience/output instead of customer name. Go through the list of tags for each release and remove any that are no longer used (or “dead”).
Choose channels on evidence, not habit
Each new channel to publish on will impose new maintenance costs that quickly add up to more than the initial setup costs as the release cycle passes. So it’s best to list out the people who asked for a channel, the ways in which people will access it, and then determine how you will deal with it if it goes stale over time.
| Channel | Best suited to | Ongoing cost | Main failure mode |
| Responsive web help | Search-driven troubleshooting | Low once the build is automated | Search tuning neglected |
| PDF or print | Procurement, audit, field use offline | High, layout needs review each build | Outdated copies circulating |
| In-product help | Short task guidance at point of need | Medium, tied to release cycle | Context mapping drifts from the UI |
| Knowledge base sync | Support deflection and agent use | Medium, depends on API stability | Duplicate articles written by support |
| Mobile or embedded app | Technicians away from a desk | High, separate testing surface | Images unreadable at small sizes |
Make the build automatic and the review human
Manual distribution to all output channels is bad, very bad. As soon as distributing your content to all channels takes more than just clicking ‘Send’ then someone will pretty soon start to neglect sending updates to the less critical channels. Include your builds into your existing pipeline (e.g. For your product releases) so that whenever you merge changes to the release branch then all output channels are regenerated automatically.
Depending on the structure of your documentation, you can use Component Content Management Systems (CCMS), DITA toolchains or, if you want a single authoring environment that already handles multi-channel targets, something like MadCap Flare documentation software. What is important is that scripted builds for all required targets are possible for all of them.
A workable release sequence
- Writers work in short-lived branches tied to a ticket, not directly in the trunk.
- Automated checks run on every commit for broken links, missing conditions, and unresolved variables.
- Reviewers see a staged web output, not source files, so feedback reflects what readers will see.
- Release builds publish all channels together and tag the source at that commit.
- After release, search queries that returned no results feed the next content backlog.
Finally, track per channel. For example, very high traffic and very high exit rates on your portal home page likely cause a set of problems entirely different from the in-product panel that no one ever opens. The fixes will be almost completely unrelated to each other as well.
