Any organisation’s technical content can become disparate and unconnected if not kept in check. Users are likely to get frustrated with your documentation if it is inconsistent or impossible to navigate, and this can give them a bad impression of your product or organisation as a whole. Without a structured plan, your authors can easily lose track of what information to include and how to write it, and reviewers and document owners can end up with very different ideas of what correct content even looks like.
The three pillars of technical documentation are there to build a framework and set a standard for the content we produce. Keeping up this standard helps readers, authors and documentation owners alike. When documentation is consistent and well-planned, everyone can focus on what is really important: the information.
Three pillars of quality technical content
1. Content Model
Each update to the product requires an update to the documentation, and the type of information required for each update is described in the Content Model.
For example, when an author comes to write about a new feature of the product, they know to add certain types of topics, and what information these topics should contain:
- Overview of the feature – Describes what the user can do with the feature and what problems it solves.
- Task topic describing how to use the feature – Step-by-step guide for a single task performed with the feature.
- Concept topic – Optional content describing any new elements that the user needs to understand.
2. Style Guide
Consistency in both terminology and style makes communicating information a lot easier for multiple stakeholders:
- Document owners can establish a style guide at the beginning of a project, setting the standard for quality and terminology early on.
- Authors can use style guides to ensure that content matches up with the overall branding, and that correct and consistent terminology is used to avoid ambiguities.
- Reviewers can use style guides as a pre-approved standard when checking over content.
- Translators have an easier, and therefore cheaper, job of translating content when phrases and terminology are repeated.
- Users know what style and terms to expect, so they aren’t distracted by learning multiple terms for the same thing, and vital information becomes easier to understand.
3. Template
After designing and creating content, it must be published. A good publishing template is tailored to the output type, and allows the reader to find information quickly and easily. It defines the page layout, whether that is printed or online, and the styling of both static and dynamic elements.
Again, the template can be developed and signed off by document owners beforehand, so that authors don’t have to worry about formatting choices. Readers are then presented with documentation which is consistent in its layout and style, and can focus on the information it contains.
Conclusion
Defining and using standard structures for content from the document level down to the word-level benefits everyone involved in the documentation process. Instead of a loosely-defined requirement, documenting a new feature becomes a measurable task performed alongside other agile development stories.
With the three pillars, we set a standard for documentation: Document owners define it; Authors write to it; Reviewers enforce it, and Translators and Readers can rely on it to provide clear, consistent content.
