Key Takeaways — Chapter 25: README Files, API Documentation, and Developer-Facing Writing

A one-page summary card. Use it to re-ground before the quiz, or to review weeks later.

The one idea

Documentation is the product's user interface for developers. For everyone who isn't you, the docs are the usable surface of your work. A developer never meets your elegant code first—they meet your README, run your install command, and copy your example. If those aren't there, or don't work, the code behind them might as well not exist: the stranger who can't get started in five minutes leaves and builds their own, exactly as Raj's twelfth visitor did. A library is precisely as good as a stranger's ability to get it working, and that ability is created entirely by your writing.

🚪 Threshold concept: Documentation is not an afterthought you write once the "real" work (the code) is done; it is the interface through which other humans encounter and judge your work. Cross this threshold and your priorities invert: you stop optimizing for completeness (covering everything you know) and start optimizing for time-to-first-success (how fast a stranger gets a working result). The quick-start jumps to the top; the architecture essay moves out of the doorway.

The core moves

  • The README is the front door—structure it around the visitor's questions. What is this (one line)? Does it solve my problem (a concrete feature list, not adjectives)? How do I install it (the exact command)? Show me it working (a runnable quick-start)? Is it maintained (badges)? Lead with the quick-start; move the philosophy down or out. Informative headings (Chapter 4) let the scanning developer jump to their question.
  • The quick-start is the most important section; time-to-first-success is the metric. The shortest path from nothing to a working result. Show the install command in a copy-pasteable block, then a runnable example showing the call and the result, minimal, ending with a link to fuller docs. Make sure it actually runs—test it on a clean machine.
  • API docs are a contract: let developers use your code without reading it. Document each endpoint completely—purpose, request (every field, typed, required-marked), response (real JSON + status code), errors (status + stable error code + meaning), and a runnable example. The errors are the part everyone skips and integrators need most, because failure-handling is where their effort goes.
  • ADRs capture the why. A short record (a page) of one decision: Context (what forced it, what was weighed), Decision, Consequences (the trade-offs accepted, including costs). Numbered, append-only (supersede, don't edit), kept in the repo. It preserves the reasoning the code can never show—so a future maintainer doesn't undo a deliberate choice. "Comment the why" (Chapter 24) at the scale of architecture.
  • Changelogs are for the upgrading user, not a commit dump. Curate; group by Added/Changed/Fixed/Deprecated/Breaking; lead with breaking changes; give every breaking change a migration path ("X removed; use Y instead").
  • Contributing guides turn willingness into merged PRs. Setup, tests, style, and a numbered submission process—so a willing stranger doesn't give up at "how do I run the tests?"

The diagnostic

The clean-machine test. You cannot judge your own README, because your machine is contaminated with everything you installed and configured months ago and forgot. Clone or copy your project somewhere fresh and follow your own install and quick-start with literal, stupid obedience—doing exactly and only what each line says—and fix every place you have to improvise. The stalls are the "how do I install this?" issues you're preventing. This is Chapter 22's "watch a beginner try" applied to software: a clean machine lacks your assumed context the way a beginner lacks your assumed knowledge.

The cautionary tales

Raj's chronoparse README was 800 words of accurate, thoughtful prose—and eleven people couldn't install it, because it answered his question (the philosophy of date parsing) and never gave an install command or a runnable example. The rebuilt README was shorter and infinitely more useful. Separately, a payments team's decision to use Redis for sessions lived only in a vanished Slack thread; six months later a new engineer nearly undid it, costing a week of meetings to reconstruct reasoning a one-page ADR would have preserved. (Case Studies 1 and 2.)

The test to apply before you publish anything developer-facing

Could a stranger—or you, on a clean machine—get this working from the documentation alone, without asking a single question?

If no, your front door is locked, and you can't see it because you're already inside the house. Run the clean-machine test and fix the stalls.

Themes this chapter surfaced: #2 audience-is-everything (the audience is a busy developer at your front door) · #5 structure-serves-the-reader (the README's order is the reader's question list) · #6 every-sentence-earns-its-place (cut the philosophy wall; the quick-start earns the top) · #1 writing-is-thinking (an ADR forces you to articulate why, which is where the reasoning becomes durable).

Threshold concept: Documentation is the product's user interface for developers; if they can't get started, the code doesn't exist to them.

Back to: Chapter 25 · Exercises · Quiz · Further Reading