Technical Documentation

Learning outcomes

You write code that works, and then you write the document that explains it, and the document is the part people complain about. They cannot find what they need, they follow your steps and hit an error you never mentioned, or they ask you in chat the very thing the page was supposed to answer. The code was the easy half. This page is about the other half: writing documentation that a reader with a goal can actually use.

After studying this page, you can:

• Identify the reader of a document, their goal, and what they already know, and write to that person instead of to yourself.
• Tell the four document types apart (tutorial, how-to guide, reference, explanation) and keep each one pure.
• Structure a long document so a skimming reader can find the part they need in seconds.
• Write with precision: define a term once, kill ambiguous pronouns, and say exactly what is true.
• Use runnable examples and explained reasoning so a reader can adapt your work, not just copy it.
• Write a README and an onboarding doc for a newcomer who knows nothing, and an architecture doc that captures the why behind the design.
• Keep documentation current and cheap to maintain, so it never drifts into the dangerous state of being confidently wrong.

Before we dive in

Here is the problem that makes this whole topic necessary. You finish a feature and write a README. To you it is obvious and complete, because you have the entire system in your head: every assumption, every prerequisite, every reason a step exists. Six weeks later a new teammate opens that README, runs the first command, and it fails, because step one quietly assumed an environment variable you set up so long ago you forgot it existed. The doc was not wrong to you. It was wrong to them.

That gap has a name in the writing world: the curse of knowledge. Once you know something, it is almost impossible to imagine not knowing it, so you skip the very steps a newcomer needs most. Documentation is the place this curse does the most damage, because the whole point of a document is to serve someone who knows less than you do. Cognitive scientists studying clear writing, such as Steven Pinker, point to this curse as the single biggest cause of unclear prose: the writer simply cannot see what the reader is missing.

So the first move in technical documentation is not a template or a tool. It is a shift of attention, away from what you want to say and toward what a specific reader, with a specific goal and specific gaps, needs to be told. Everything else on this page is a consequence of taking that shift seriously. The full clarity toolkit lives in the principles of clear prose; this page applies it to docs.

Mental Model: write for the reader, not the writer

The wrong model is that a document is a record of what you built: a place to dump everything you know about the system so it is written down somewhere. Under that model, completeness means coverage, and a good doc is one that leaves nothing out. This is the model that produces the README that is technically complete and practically useless.

The better model is that a document is a tool a particular reader picks up to reach a particular goal. Under that model, a good doc is not the one with the most information; it is the one that gets that reader to that goal with the least friction. Completeness is measured against the reader’s task, not against the system. A page that answers the reader’s question and stops is better than a page that answers it and then buries it under everything else you know.

This single shift drives every later section. Knowing the reader tells you which of the four document types to write. It tells you to put a summary up top, because the reader is skimming. It tells you to define jargon, because the reader does not share your background. It forces examples, because the reader learns faster by doing. And it makes you explain the why, because the reader will face a case you did not anticipate and will need to adapt.

Breaking it down

1. The reader with a goal

Before you write a sentence, answer three questions. Who is the reader? What are they trying to do? What do they already know? These are not warm-up questions; they decide the entire shape of the document.

Take one concrete page: the deploy instructions for a web service. The same subject produces three completely different documents depending on the reader.

• A brand-new hire who has never deployed here needs every step spelled out, including how to get access and what a successful deploy looks like.
• An experienced engineer doing a routine release needs a short, scannable checklist they can run in two minutes, with the rollback command at the bottom.
• An on-call engineer at 3 a.m. during an incident needs the one command to roll back, at the very top, with nothing in the way.

Same topic, three readers, three goals, three documents. If you write one page for all three, you serve none of them: it is too long for the expert, too terse for the newcomer, and too slow for the incident. The reader is not a detail you fill in later. It is the first decision, and it is the one that most often goes unmade.

2. The four document types, and why mixing them hurts

Most bad documentation is not badly written. It is two good documents fighting inside one page. A reader comes to learn the basics and trips over a wall of configuration options; another comes to look up one flag and has to wade through a beginner’s tutorial to find it. The cure is to recognize that documentation serves four distinct purposes, and a single document should serve only one. This four-way split is widely known as the Diataxis framework.

The four types differ along two axes: whether the reader is studying or working, and whether they need practical steps or theoretical background. Knowing which quadrant you are in tells you the shape, the voice, and what to leave out.

Read the table as a set of promises. A tutorial promises that if you follow along, it will work, so it never offers a choice that could go wrong. A how-to guide promises to get one job done, so it assumes you already know the basics and skips them. A reference promises completeness and accuracy, so it is dry and exhaustive on purpose. An explanation promises understanding, so it is allowed to wander into history and trade-offs that the other three must cut.

The diagram below turns the same four types into a decision you can run in your head before you write.

The payoff of the framework is permission to leave things out. Once you have decided a page is a how-to guide, you are allowed, even required, to skip the conceptual background and the full list of options, because those belong in the explanation and the reference. Mixing them is not generous; it is the thing that makes the page hard to use. When a doc feels bloated, the usual fix is to notice it is two types in a trench coat and split it in two.

3. Structure for the skimming reader

A reader skims, so structure is not decoration; it is how they navigate. Three habits make a long document usable.

First, descriptive headings. A heading is a signpost a skimming reader reads instead of the paragraph beneath it. “Configuration” tells the reader almost nothing; “Configure the database connection” tells them exactly whether to stop here. Write headings as answers or tasks, not as one-word topics, so a reader scanning the left margin can route themselves without reading the body.

Second, a short summary or overview at the very top. Before any detail, tell the reader in two or three sentences what this document is, who it is for, and what they will be able to do after it. This is the cheapest, highest-value paragraph on the page, because it lets a reader decide in five seconds whether they are in the right place, instead of reading half the page to find out they are not.

Third, a table of contents for any long document, so a reader can jump straight to their section instead of scrolling and hunting. The page you are reading opens with exactly this, for exactly this reason.

4. Precision: say exactly what is true

Documentation is read literally, often by someone tired, stressed, or new, who will do exactly what the words say. Vague writing that a human would charitably interpret in conversation becomes a trap on the page. Precision is the discipline of removing every reading except the one you mean.

Three precision habits matter most. Define each term once, the first time it appears, and then use that exact term every time after, never a casual synonym. If you call it a “job” in one place and a “task” in another and a “run” in a third, the reader cannot tell whether those are three things or one. Consistency is not dullness; it is mercy.

Next, kill ambiguous pronouns. The most dangerous word in technical writing is “it” with no clear owner. Usage authorities like Bryan Garner single out the unanchored pronoun as a leading source of avoidable ambiguity. Look at the difference a single rewrite makes.

The rewrite is a few words longer and infinitely clearer, because it leaves the reader nothing to guess. Third, cut vague quantifiers. “The operation may take a while” tells the reader nothing they can act on; “the operation usually finishes in under thirty seconds, and you can safely wait up to five minutes” lets them know when something is actually wrong. Say the true, specific thing.

5. Examples carry more than prose

A concrete example teaches faster than any amount of description, because the reader can see the shape of the answer instead of assembling it from rules. This is the same principle that makes a worked problem clearer than a stated theorem: show the specific case, and the general rule becomes obvious.

Compare a parameter described in prose with the same parameter shown.

Two rules make examples trustworthy. Make them runnable: an example a reader can copy, paste, and run unchanged builds confidence, while an example with hidden setup or placeholder values that do not work destroys it. And make them realistic: prefer a plausible filename and value over foo and bar, because the reader is trying to map the example onto their real situation, and abstract placeholders make that mapping harder.

6. The why, not just the what

A reader who only knows what to do can follow your exact path. A reader who also knows why can adapt when their situation differs from yours, which it always eventually does. The why is what turns a reader from a copier into someone who can think with your system.

Suppose your setup doc says: “Set the connection pool size to 10.” A reader whose service handles ten times your traffic will dutifully set it to 10 and then wonder why the database is starved, because the doc gave them a value without the reasoning. Now suppose it says: “Set the connection pool size to roughly twice your peak concurrent requests; we use 10 because we peak around 5.” That reader sets theirs to 200 and moves on. The same two extra clauses turned a brittle instruction into one the reader can adapt to a case you never saw.

This is not a license to explain everything. The why belongs where a reader might reasonably need to adapt or might otherwise distrust the instruction. The deep version of this, where a whole document exists to record the reasoning behind a design, is the architecture doc, which we turn to in section 8.

7. The README and the onboarding doc

The README is the front door, and the onboarding doc is the guided first day. Both are written for the same person: the newcomer who knows nothing about this system. That is exactly the reader the curse of knowledge hides from you, which is why these are the two documents most often written for the wrong audience, the author.

A README answers, in order, the questions a newcomer asks: What is this? (one or two sentences, in plain words, no internal jargon.) Why would I use it? (the problem it solves.) How do I get it running? (the shortest path from nothing to a working example, every step, no assumed setup.) Where do I go next? (links to the deeper docs.) Notice that this is a tutorial in miniature: a guaranteed path from zero to a first success, because nothing earns a newcomer’s trust like getting something to work in the first five minutes.

The onboarding doc extends that first success into a working setup: how to get access, how to run the tests, how to make a first small change and see it take effect, and who to ask when stuck. The test of both documents is brutal and simple: hand the doc to someone who has never seen the system, watch them follow it without helping, and write down every place they get stuck. Each stuck point is a step your knowledge let you skip. Fixing those is most of what makes a README good.

8. Architecture docs: overview, context, decisions

An architecture doc explains the shape of a system and, above all, why it has that shape. Its reader is a future engineer, often you in a year, trying to understand or change the system without the context that was in everyone’s head when it was built. Three parts carry most of the value.

Start with an overview: a short, high-level picture of the main pieces and how they fit, the thing a new engineer needs before any detail will make sense. Then the context and constraints: what the system has to do, what it must not do, and the limits it was built under, such as a traffic level, a budget, a deadline, or a rule it has to obey. A decision only makes sense against the constraints that forced it, so the constraints come first. Finally, the key decisions: the handful of choices that shaped everything else, each paired with the reason it was made and, ideally, the alternatives that were rejected and why.

The rejected alternatives are the part newcomers value most and authors most often omit. Recording why you did not use the obvious approach saves a future engineer from re-proposing it, re-arguing it, and rediscovering the same wall you already hit. The full, formal version of this genre, the proposal that argues for a decision before it is made and records the discussion around it, is a discipline of its own, covered in writing RFCs and design docs. This section is the lightweight, after-the-fact record; that page is the heavyweight, before-the-fact proposal.

9. Keeping docs current

A correct document helps. A missing document is a known gap. But a wrong document is worse than no document at all, because it actively misleads a reader who trusts it, and trust is exactly what documentation runs on. A newcomer who follows a stale step into an error does not just lose time; they stop believing the docs, and after that they ask you in chat instead, which is the failure the docs existed to prevent.

So currency is not a nice-to-have; it is the whole value, because an out-of-date doc has negative value. The practical defense is to make docs cheap to keep correct, so that keeping them correct survives contact with a busy schedule.

• Keep the doc near the thing it documents, ideally in the same repository, so a change and its doc move together and a reviewer sees both in one place.
• Write fewer, more durable claims. State things that change slowly (what the system is for, why it is shaped this way) and link to the code or generated output for things that change fast (exact flag lists, function signatures). A precise value that drifts becomes a lie; a stable principle stays true.
• Delete aggressively. A short, current doc beats a long, half-stale one. When in doubt, cut the part you are least sure is still true, because a wrong section poisons the reader’s trust in the right ones.

Common mistakes

Each mistake below is the same root error wearing a different outfit: writing for yourself instead of the reader.

Writing for yourself is the parent of all of them. You include what you find interesting, in the order it occurred to you, in the vocabulary you happen to use, and call it done. The fix is the whole of this page: name the reader and their goal first.

Skipping examples is the most common and most expensive. Prose alone forces the reader to construct the concrete case in their head, slowly and unreliably. One runnable example does the work of three paragraphs. If a page has no example, that is usually the first thing to fix.

Unexplained jargon is the curse of knowledge made visible. You use an internal term, an acronym, or a tool name as if everyone knows it, because to you they do. The newcomer stops cold. Define each term on first use, or link to where it is defined.

Ambiguity, especially the pronoun with no owner, lets a literal reader take the wrong branch. The page reads fine to you, who knows what “it” means, and misleads the reader, who does not. Replace the pronoun with the noun.

No structure makes a correct document invisible to a skimmer. Without descriptive headings, a summary, and a table of contents, the reader cannot find the part that would have helped, so it might as well not exist. Structure is not polish; it is access.

Stale docs are the slow killer. A doc written once and never touched again drifts from helpful to misleading without anyone noticing. Put the doc next to the code, keep its claims durable, and update it as part of the change that dated it.

Mastery Questions