Documentation philosophy¶
Documentation is not a deliverable. It is infrastructure.
A deliverable is produced once and handed over. Infrastructure is maintained, because the system it supports can't function without it. The moment you treat documentation as a deliverable, you've decided it will be out of date within six months and nobody will trust it.
The three questions¶
Every document I build starts with three questions.
Who arrives without context? Documentation isn't written for the person who already knows. It's written for the person who arrives cold — a new team member, an external contributor, future you at 3am when something breaks. If it requires prior knowledge, it's incomplete.
What is the single source of truth? Every fact has a home. One home. If a measurement appears in three documents, it will eventually appear with three different values — and the reader can't know which is right. The only fix is architecture: one place where each fact lives, referenced everywhere else. More in Single source of truth.
What happens when it changes? A system that can't be maintained won't be maintained. Simplicity is the precondition for longevity. Every structural decision passes through one filter: what does the person who inherits this in two years need to do to update it?
Where this came from¶
The editorial discipline of running a monthly magazine — deadlines, consistency, the gap between accurate and useful. Years later I applied it deliberately to libdrone, where the documentation had to work without me. That constraint is clarifying: you learn quickly what's missing.
What I've learned¶
Architecture is the work. A well-structured document with mediocre prose is useful; a beautifully written document with no structure is noise.
Length is not quality. The best technical documentation is dense and short. The worst is long because nobody made the hard editorial cuts.
The reader is not you. Every implicit assumption, every undefined term is a tax the reader pays. Good documentation minimises the tax.
Maintenance is the hardest part. Unmaintained documentation is actively harmful — it describes something that no longer exists and misleads the people who trust it.