Raising the bar: The three pillars of quality technical content
by George Lewis
by George Lewis
In this article
1. Content Model
2. Style Guide
3. Template
Conclusion
About the author
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.
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:
Consistency in both terminology and style makes communicating information a lot easier for multiple stakeholders:
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.
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.
George works as 3di’s Service Delivery Director. Passionate about helping each individual team member reach their full potential. Outside of work George can be found cycling, reading books on business and psychology, as well as taking the odd trip to Spain or Germany.