The documentation system#
The Grand Unified Theory of Documentation
- David Laing
There is a secret that needs to be understood in order to write good software documentation: there isn’t one thing called documentation, there are four.
They are: tutorials, how-to guides, technical reference and explanation. They represent four different purposes or functions, and require four different approaches to their creation. Understanding the implications of this will help improve most documentation - often immensely.
About the system#
The documentation system outlined here is a simple, comprehensive and nearly universally-applicable scheme. It is proven in practice across a wide variety of fields and applications.
There are some very simple principles that govern documentation that are very rarely if ever spelled out. They seem to be a secret, though they shouldn’t be.
If you can put these principles into practice, it will make your documentation better and your project, product or team more successful - that’s a promise.
The system is widely adopted for large and small, open and proprietary documentation projects.
- Analogy from cooking
- How to write good tutorials
- Example from Divio’s documentation
- How-to guides
- Reference guides
- About the structure
- Who is using the system?
If you’d prefer to watch a video covering this topic, here is it (courtesy of PyCon Australia 2017).