Writing Technical Documentation People Actually Read

What it does NOT contain: the entire API surface, contribution guidelines, full architecture, deployment instructions. Each of those belongs in its own document. The README points to them.

The shortest README that hits all six questions is usually the best README. Long READMEs are READMEs that became documentation by accident.

## The Architecture Doc — Decisions, Not Just Diagrams

The architecture doc explains how the system is structured and **why**. The "why" is the part most teams skip, and it is the most valuable part. Six months from now, the team will have forgotten the constraints that drove a decision; without the why captured, they will revisit the decision repeatedly.

A good architecture doc has these sections:

1. **System overview** — a paragraph and a diagram.
2. **Major components** — what each one does, what it uses.
3. **Data flow** — how a typical request moves through the system.
4. **Key decisions** — choices that could have gone differently, and why they did not.
5. **Trade-offs accepted** — what is hard or impossible because of the design.
6. **What we considered and rejected** — alternatives evaluated, with a sentence on why each was passed over.

The "decisions" section is where a senior engineer's writing shows. "We use SQLite because the workload is read-heavy and single-machine; we considered Postgres but the operational cost outweighed the benefit at this scale" tells a future reader more than any diagram.

For diagrams, use **boxes and arrows in plain text or Mermaid**, not heavy UML. The point is to convey the structure, not to satisfy a methodology. A diagram that requires explanation has failed.

For decisions of any weight, write an **Architecture Decision Record (ADR)** — a short document for each major decision (a few pages), kept in version control, never edited after acceptance. The ADR pattern (popularized by Michael Nygard) gives you a project-history audit trail of "what did we decide, when, and why."

## The API Reference — Boring Is the Goal

API reference docs are the one place in technical writing where boring is correct. The reader is not learning concepts; they are looking up specific endpoints under time pressure. Every flourish gets in the way.

The standard structure for each endpoint:

- **Method and path** — `POST /api/tasks`
- **Description** — one sentence about what it does.
- **Authentication** — what is required.
- **Parameters** — query params, path params, body fields, with types and constraints.
- **Response** — status codes and response shape.
- **Errors** — what specific errors mean and how the client should handle them.
- **Example** — a working request and response.

For larger APIs, generate this from a single source of truth — an OpenAPI spec, a tRPC schema, GraphQL introspection. Hand-maintained API reference docs drift from the implementation within weeks. Generated reference docs cannot.

For small APIs, hand-written reference is fine. Just commit to keeping it accurate when the API changes; out-of-date documentation is worse than no documentation because it actively misleads.

## The How-To Guide — One Specific Task

A how-to guide answers a single question: "How do I do X?" Where X is a concrete task. "How do I deploy a new version." "How do I add an authenticated route." "How do I run the test suite locally." Each how-to is a separate document, focused, with a clear ending.

The structure:

1. **What you'll accomplish** — one sentence describing the end state.
2. **What you need first** — prerequisites, in priority order.
3. **The steps** — numbered, in order, each one short.
4. **How to verify it worked** — what success looks like.
5. **What to do if it didn't work** — common failure modes with their fixes.

The last point is what separates great how-tos from mediocre ones. A guide that ends with "you should now have X" without telling you what to do when you obviously do not have X is a guide that fails the reader at the worst possible moment.

For complex workflows, the troubleshooting section is often longer than the happy-path steps. That is correct. The happy path is short because it is well-understood; the failure paths are long because there are many.

## The Runbook — When Something Is On Fire

A runbook is a document for the on-call engineer at 3am. The reader is sleep-deprived, anxious, and needs to fix the problem fast. Everything about runbook writing is in service of that scenario.

What a runbook needs:

- **A clear trigger.** "If you got paged for HTTP 5xx rate > 1% on the api-gateway service, this is the runbook for that."
- **Quick triage.** "First, check the dashboard at <link>. If [observation], skip to step 3."
- **Specific commands.** Not "check the database for issues" but "run `psql -h prod-db -c 'SELECT count(*) FROM pg_stat_activity'`."
- **What good looks like.** "Healthy is < 50 connections. > 200 means connection leak."
- **Escalation paths.** "If still failing after step 5, page the database team via <link>."
- **Postmortem template link.** When the fire is out, the next step is the writeup.

A good runbook is the difference between a 5-minute incident and a 5-hour one. Engineers rarely thank the person who wrote the runbook, but the runbook author has saved many hours of pager time across the team.

## Writing Principles That Actually Matter

Beyond the structure of each document type, a small set of writing principles distinguishes the documentation people actually read:

**Write for the reader, not the writer.** The question to ask is not "did I cover everything I know" but "what does the reader need to know right now." Documentation as memoir helps no one.

**Be honest about limitations.** A README that admits "this is a learning project, do not use it in production" is more useful than one that claims it is "production-ready" when it is not. Trust comes from accurate self-description.

**Examples are worth their weight.** A working example is the fastest path to understanding. Every concept that has an example gets understood faster than every concept that does not.

**Maintain ruthlessly.** Out-of-date documentation actively misleads. When a doc no longer matches the code, either fix the doc immediately or delete it. There is no middle ground that helps the reader.

**Use the language the reader uses.** If everyone calls it a "container," do not call it a "self-contained execution environment" because it sounds more precise. Match the vocabulary your audience already has.

**Short sentences. Real verbs.** "The system processes requests" beats "Request processing is performed by the system." Active voice and concrete verbs make the meaning land. Most academic-sounding documentation became academic-sounding by accident, not because the topic required it.

## What to Do First

If you are looking at a project with bad documentation right now and wondering where to start:

1. **Write the README.** Six questions, in order. An hour, maybe two.
2. **Write one ADR for the most controversial recent decision.** Captures the most institutional knowledge for the least time.
3. **Write a runbook for the most common production incident.** Saves the most pager time.
4. **Generate the API reference from your spec.** Replaces hand-written docs that drift.
5. **Write how-tos as you do tasks.** Whenever you do something for the second time, the act of doing it is also the act of writing the how-to for whoever does it third.

Six hours total, distributed over a few weeks. Most projects do not do this and pay for it forever. Doing it once and then keeping it current is one of the highest-leverage investments an engineer can make in their team.

## Where This Fits

Lesson 18 of the ABCsteps curriculum has you write the documentation for your project. This article gives you the structures professional engineering teams use so the lesson's deliverable looks like a senior engineer wrote it. The lesson's project will need a README, an architecture doc, an API reference, and at least one how-to. With this article in your head, each of those becomes a known shape you can fill in, not a blank page to stare at.