The cloud infrastructure management service Divio has published a system of what a good documentation should look like (especially for hardware/software companies). Their system splits documentation into four pillars: tutorials, how-to guides, explanations and references.
Source: https://documentation.divio.com Keywords: knowledge-management, documentation
The Four Pillars
Tutorials are written from the perspective of a teacher, instructing the reader to follow a set of steps to come to an end goal. It’s not necessary for the reader to understand the complexity of the explained system, the importance lies in teaching them how to get started with a product and give them confidence in their ability to use it.
- immediate results
- repeatability
- concrete steps
- minimum explanation
- set focus: only one possible way, defined by the steps given
How-to guides are aimed at more experienced users that have a specific question and goal in mind. They also outline steps but always solve a particular problem.
- reaching practical goals
- no abstract concepts
- flexibility: different options of achieving the same
Reference guides are technical descriptions of the system and its proper/intended use. If the product is a piece of software, the reference guide will be based on the code base itself and any exposed API endpoints.
- structured around the inner workings of the product, e.g. the codebase
- importance of consistency & accuracy
- descriptions only!
Explanations, discussions and clarifications build the broader context around the documentation and build understanding of the product.
- there’s no one-right-way to do this
- might be design decisions, historical artifacts and constraints
- alternative approaches
Why is this useful?
This approach could be used in future projects or existing ones such as Kosh’s documentation site.
