Skip to main content

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

overview of the documentation 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.

Video presentation

If you'd prefer to watch a video covering this topic, here is it (courtesy of PyCon Australia 2017).
https://docs.divio.com/documentation-system/
docs.divio.com
CC-MAIN-2024-30
18035
application/http; msgtype=response
sha1:55LWVOSK5ITDHX7ABKSTQDYRMMXAM6AH
<urn:uuid:f67bd7ab-c88b-4188-ae5f-4cfa56f0aa2f>
2024-07-20T15:10:18Z
104.18.26.57
text/html
sha1:SXSCJRBNBSC7ZYS2MIDWJRKZVRDU6AYN
<urn:uuid:83539932-fb49-4c53-b190-99239dcb7ca6>
https://docs.divio.com/documentation-system/
response
<urn:uuid:3f8c2852-4e2a-4012-8db6-14952f2d0e11>
isPartOf: CC-MAIN-2024-30
publisher: Common Crawl
description: Wide crawl of the web for July 2024
operator: Common Crawl Admin (info@commoncrawl.org)
hostname: ip-10-67-67-196
software: Apache Nutch 1.20 (modified, https://github.com/commoncrawl/nutch/)
robots: checked via crawler-commons 1.5-SNAPSHOT (https://github.com/crawler-commons/crawler-commons)
format: WARC File Format 1.1
conformsTo: https://iipc.github.io/warc-specifications/specifications/warc-format/warc-1.1/