The documentation team grows faster than the documentation tooling can keep up with. It can take some time until the signs are there in black and white, In the run-up to the release, reviews take longer, safety-related content is duplicated in nine versions for four products and the costs for translating new content exceed the costs for the word count of newly created content significantly. Then the question changes from “which tool do the authors prefer?” to “which system can manage the structure of the content and the associated processes and output channels for dozens of authors?”.
In this section we are going to discuss several ways to manage documentation in large teams. We will outline each of these options in more detail and also highlight the most important criteria to consider when selecting a workbench for your team.
The three architectures that actually scale
There are only three ways to proceed to support larger teams
Docs-as-code repositories
Writing your content in Markdown or reStructuredText in a Git repository. The content is then generated by static site generators (SSGs) and reviewed via pull requests. For a team of developers this will work just fine as long as the content follows the code and there is mostly one output (e.g. HTML files for a website). Reusing content across product lines with varying metadata, non-technical authors reviewing within the completed document, translated content being sent to vendors as segmented and versioned files rather than diffed files are examples of cases where this will not work.
Component content management systems
A database-backed repository for topics as small self-contained components (as opposed to single larger documents), supporting reuse, branching and release management. If your output is primarily manuals and help systems, consider a CCMS for technical documentation. It works best for teams who have developed a solid information model for their documentation. People without that will not get much out of it.
Headless CMS with a structured schema
This architecture is particularly well-suited when documentation is mixed with other marketing content, such as blog articles. In-product help or support knowledge base content is also a good candidate. However, generating PDFs, conditional output and print-quality page design is not usually done by the same architecture that delivers HTML content to read online.
Comparing the options against team realities
| Criterion | Docs-as-code | CCMS | Structured headless CMS |
| Reuse granularity | File and include level | Topic, element, and variable level | Entry and field level |
| Translation handling | External, often manual | Built in, with change-only export | Varies by vendor |
| Non-writer contribution | Low without training | Medium, via web editors | High |
| Print and PDF output | Weak to adequate | Strong | Requires add-ons |
| Audit and compliance trails | Commit history only | Full workflow history | Partial |
| Setup effort | Weeks | Several months | Weeks to months |
Designing reuse before you buy anything
Your content will in the beginning mostly reproduce the already existing structures of content in the other systems that you are using for your documentation. But mostly duplicated and with increased cost of maintenance.
Approach this process in the following sequence
- Audit a representative slice of content and tag every passage that appears more than once, noting whether the duplicates are identical, near-identical, or merely similar in intent.
- Separate true reuse candidates, such as procedures and specifications, from accidental similarity that should stay independent.
- Define the variation axes that matter, for example product model, region, audience, and firmware version, and cap the number deliberately.
- Decide where variables end and conditional content begins, since overusing conditions makes topics unreadable in the authoring view.
- Write the rules down as a short, enforceable style and structure guide, then test it against the hardest content you have.
The governance layer that makes reuse survive
Assign authors to the shared components (Reusable Topics), show them all the other authors for a Reusable Topic, and list all the publications down the line that will include this piece of content. Nobody wants to write something that others can misuse with catastrophic results down the line.
Workflow design for teams above twenty contributors
When it comes to scale issues at documentation teams, writers not writing fast enough is not the main problem. Slow review cycles, unknown approval scopes and change induced rework are much bigger issues. Three things help quickly to solve these kinds of problems.
- Move review to the topic level so reviewers see only what changed, with context, rather than an entire manual.
- Set approval by content type rather than by publication, so a legal reviewer handles warnings across all products instead of per release.
- Freeze the structure before the content, locking the topic map early so late edits cannot reshape the output.
Making the decision defensible
A pilot project using the “real stuff” (i.e. Not only some example files but e.g. A product family, written in the desired complexity, e.g. Translated, different versions for different products) helps to find potential problems quickly. The complete content is migrated to the new workbench and all features are tested with real life scenarios. Measuring the time to create new content, the amount of words that need to be translated and the number of review rounds for each component before and after the pilot helps to identify problems early.
In all unusual cases where even a very successful pilot did not decrease two of these three indicators, the problem is with the content model and any amount of conversion will not fix fundamental problems of managing content.