Technical documentation: what you should receive with your software
The eight documents that let a competent stranger run, change and extend your software, and the test that shows whether they are complete.
The short answer
Software you own is software a competent stranger could run, change and extend from the documentation alone. Eight documents make that possible, and none needs to be long: a system overview, setup and run instructions, a record of architecture decisions with reasons, the data model, the list of integrations and how their credentials are laid out, an operations runbook, the release process, and a guide for users and administrators. They live next to the code in the repository, are updated as part of any change that affects them, and are reviewed with the code. The test is simple: hand the documents to a developer who has never seen the system and see whether they can set it up, make a change and deploy it. If not, the missing answers are the missing documentation.
The eight documents
| Document | Contents | Length |
|---|---|---|
| 1. System overview | What it does, for whom, the main pieces and how they connect, one diagram | One page |
| 2. Setup and run | Exactly how to get it running locally and in each environment: tools, versions, commands, configuration | One to two pages, tested |
| 3. Architecture decisions | Each significant choice: what was decided, why, alternatives considered, date | A short entry per decision |
| 4. Data model | The main entities, their relationships and meanings; a diagram; notes on sensitive fields | A page plus a diagram |
| 5. Integrations | Every external system: purpose, API, credentials layout (names and where they live, never values), owner, failure behaviour | A table |
| 6. Operations runbook | Monitoring, alerts and what to do for each, backups and restore steps, common incidents, contacts | A few pages |
| 7. Release process | How a change goes from branch to production: pipeline, checks, approval, rollback, migrations | One page |
| 8. User and admin guide | How the people who use and administer it do the main tasks, with screenshots where useful | As needed, per role |
Keeping it alive
- Store it in the repository, next to the code, so it is versioned and reviewed like everything else.
- Make it part of done: a story that changes setup, data, integrations, operations or release steps updates the relevant document in the same change.
- Test the setup document whenever a new developer joins; their questions are its gaps.
- Date every document and review the set quarterly.
- Keep it short; a document that is too long to read is not documentation.
The stranger test
Give the repository and the documents to a developer who has never seen the system. Ask them to set it up locally, make a small change, run the tests and deploy to a preview, using only the documents and asking no one. Count the questions they would have needed to ask. Zero means the software is documented. A few means small gaps to close. Many means the documentation is a promise, and the knowledge is still in people.
What this means for you
Expect eight short documents in the repository, kept current as part of every change, and run the stranger test before accepting any hand-over. Documentation is the difference between owning software and depending on the people who built it, and it costs a fraction of what its absence costs the day those people are unavailable.
Frequently asked questions
How much documentation is enough?
Enough for the stranger test and no more. Long documents go stale and unread; a short overview, precise setup steps, a list of decisions with reasons, a data model diagram, an integration list, a runbook for operations, the release steps and a user guide cover it for most systems. Each should be a page or a few, kept current in the repository.
Who keeps it up to date?
Whoever makes a change that affects it, as part of that change; it is reviewed with the code. A documentation update is part of the definition of done for any story that changes setup, architecture, data, integrations or operations. Documentation maintained separately, later, by someone else, is documentation that decays.
What about the code itself?
Readable code with clear names, types and a few comments explaining why rather than what, is the first layer of documentation and the one that never goes stale. The eight documents sit above it and explain the things code cannot: the decisions, the context, the operations, the people.