Documentation philosophy¶

Documentation is not a deliverable. It is infrastructure.

A deliverable is something you produce once and hand over. Infrastructure is something you maintain because the system it supports cannot function without it. The moment you treat documentation as a deliverable, you have already 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 is not written for the person who already knows. It is written for the person who arrives cold — new team member, external contributor, future you at 3am when something breaks. If the document requires prior knowledge to understand, it is incomplete.

What is the single source of truth? Every fact in a documentation system has a home. One home. If a measurement appears in three documents, it will eventually appear in three documents with three different values. The reader cannot know which is correct. The writer cannot maintain all three. The only solution is architecture: one place where each fact lives, and everywhere else references it.

What happens when it changes? A documentation system that cannot be maintained will not be maintained. Simplicity is not laziness — it is the precondition for longevity. Every structural decision I make is filtered through: what does the person who inherits this project in two years need to do to update it?

Where this came from¶

I ran a technology magazine in my twenties. The editorial discipline of a monthly publication is not very different from the discipline of a good documentation system. Deadlines, consistency, version control, the difference between what is accurate and what is useful. I brought all of it into technical documentation without knowing that was what I was doing.

Twenty five years later I applied it deliberately to libdrone — an open hardware platform that needed documentation good enough for a competent stranger to reproduce the hardware without ever contacting the author. That constraint is clarifying. When the documentation has to work without you, you learn quickly what is missing.

What I have learned¶

Architecture is the work. The writing is secondary. A well-structured document with mediocre prose is useful. A beautifully written document with no structure is noise. Every hour spent designing the architecture before writing pays back in multiples during maintenance.

Length is not quality. The best technical documentation I have read is dense and short. Every sentence earns its place. The worst is long because nobody made the hard editorial decisions about what to cut.

The reader is not you. You know the system. The reader does not. Every shortcut you take, every assumption you leave implicit, every term you use without defining — these are taxes the reader pays. Good documentation minimises the tax.

Maintenance is the hardest part. Writing the first version is satisfying. Maintaining it as the system evolves is unglamorous and essential. Documentation that is not maintained becomes actively harmful — it describes something that no longer exists and misdirects the people who rely on it.