How to Write Documentation Developers Actually Read

Everyone wants good documentation and almost nobody wants to write it. The result is familiar: a README that says "TODO," setup steps that stopped working two years ago, and knowledge that lives only in one person's head. Good documentation doesn't have to be long. It has to answer the questions people actually have, and stay true.

Know who you're writing for

Different readers need different documents:

Reader	Needs
New developer	How to install, run, test and deploy
Teammate changing code	Why things are the way they are
API consumer	Endpoints, parameters, examples, errors
Future you	Context you'll definitely forget

Write each document for one audience. Mixing them produces documents that serve nobody well.

The README: your project's front door

A good README answers, in order:

1. What is this? One or two sentences.
2. How do I run it? Prerequisites and exact commands.
3. How do I test it?
4. How is it configured? Environment variables (point to .env.example). (Config best practices.)
5. How is it deployed?
6. Where do I learn more? Links to deeper docs.

A template:

# Invoice Service

Generates and emails PDF invoices for completed orders.

## Requirements
- Node.js (version in .nvmrc)
- Docker (for the local database)

## Getting started
```bash
cp .env.example .env
docker compose up -d db
npm ci
npm run migrate
npm run dev
```

## Tests
`npm test` runs unit and integration tests.

## Deployment
Merges to `main` deploy automatically via GitHub Actions.

The test of a good README: can a new developer go from clone to running app without asking anyone? Try it on a fresh machine, or ask the next new teammate to note every step that confused them.

Comments: explain why, not what

// Bad: restates the code
// loop through users
for (const user of users) { ... }

// Good: explains a non-obvious reason
// The CRM rejects batches over 100 records, so we send in chunks.
for (const batch of chunk(users, 100)) { ... }

Good comments capture intent, trade-offs, workarounds and links to the issue or documentation behind a decision. If code needs a comment to explain what it does, try clearer names first. (Clean code tips.)

Architecture Decision Records (ADRs)

An ADR is a short document recording a significant decision:

# 007: Use PostgreSQL for the main database

## Status
Accepted

## Context
We need relational data with transactions for orders and payments...

## Decision
Use PostgreSQL with a managed provider.

## Consequences
+ Strong consistency, mature tooling
- Team needs to learn connection pooling for serverless functions

ADRs answer the question every new developer eventually asks: "Why on earth did we do it this way?" Keep them numbered in a docs/adr folder. They're short, they never need updating (you write a new one to supersede an old one), and they're invaluable a year later.

API documentation

For APIs, generated documentation from an OpenAPI specification is hard to beat: it stays close to the code, shows every endpoint and schema, and offers interactive testing. Add what generators can't:

• A getting-started guide with authentication
• Realistic request and response examples
• Error formats and what each error means (consistent errors)
• Rate limits and pagination rules

Keep docs close to the code

Documentation that lives far from the code (a forgotten wiki page) goes stale quickly. Docs as code means:

• Docs live in the repository, in Markdown.
• Changes to docs go through pull requests, like code.
• Pull request templates ask: "Did you update the docs?" (Code review habits.)

Writing tips that make docs readable

• Lead with the answer. Put the command or the conclusion first, explanation after.
• Use short sections and headings so people can scan.
• Show examples. One working example beats three paragraphs of description.
• Use exact commands that can be copied and run.
• Date or version things that change, like supported versions.
• Delete outdated docs. Wrong documentation is worse than none.

Make it a habit, not a project

Documentation sprints produce docs that rot. Instead, write a little as you go:

• Fixed a confusing setup problem? Add a line to the README.
• Made a significant decision? Write a short ADR.
• Answered the same question twice in chat? That answer belongs in the docs.

FAQ

What should a README include?

What the project does, how to install and run it, how to test it, how it's configured, how it's deployed and where to find more documentation.

What is an Architecture Decision Record?

A short document capturing an important technical decision: its context, the decision itself and its consequences. It explains why the system is built the way it is.

How do I keep documentation up to date?

Keep docs in the repository next to the code, update them in the same pull requests as code changes, and delete or fix outdated content as soon as you notice it.