top of page

Write Clear READMEs — Technical Writing for Engineers, Part 3

Shift Quality Editorial
28 minutes ago
7 min read
Technical Writing for Engineers · Part 3

A contractor starts on Monday at a logistics company. The service they'll work on has a good-looking README: badges, a quick start, a section on architecture. They follow the quick start exactly. Step three installs a dependency at a version that no longer exists. Step four refers to an environment variable that was renamed a year ago. By lunchtime they've given up on the README and are messaging the one engineer who knows how the service actually starts. That engineer is in back-to-back meetings until Wednesday.


Every line of that README was true when it was written. Nobody changed it when the code changed, and nothing told anyone it had gone wrong.


The working claim for this part: a README is a promise about how to get started, and like any promise in software it goes stale silently unless something checks it. Decide what belongs in it, then test it like code. The live post Writing a README That People Actually Use covers what to put in one. This part is about keeping what you put there true.


Before you start


  • Pick a repository your team owns that someone new will need to use in the next few months.

  • Find a clean environment: a fresh container, a new virtual machine, or a colleague's laptop that has never run the project.

  • Note how long it took the last new joiner to get the project running, if anyone knows. That's your baseline.


Step 1: Decide what the README is for (10 min)


Daniele Procida's Diátaxis framework distinguishes four kinds of documentation, serving four different needs: tutorials (learning-oriented), how-to guides (task-oriented), reference (information-oriented) and explanation (understanding-oriented). READMEs fail when they try to be all four at once. The result is a long page where the one thing a newcomer needs, how to get the project running, is buried under architecture notes and configuration tables.


A practical split: the README is a short how-to guide for the first hour, getting the project running and making a first change, plus pointers to everything else. Reference material, such as every configuration option, and explanation, such as why the architecture looks the way it does, live in their own documents and are linked.


Test you can run: go through your README section by section and label each one tutorial, how-to, reference or explanation. Anything that isn't helping someone through their first hour is a candidate to move to its own page and link.


Step 2: Write the first hour as numbered, copyable steps (15 min)


The quick start should be a sequence a newcomer can follow without making decisions: numbered steps, each with a command they can copy, and the output they should expect to see. "Set up your environment" isn't a step. "Run make setup; you should see Setup complete" is.


State the prerequisites with versions, and say how to check them. Where a step can fail in a common way, put the fix right under the step, not in a troubleshooting section at the end.


Test you can run: read your quick start and circle every place where the reader has to make a choice or already know something you didn't write down. Each circle is either a missing step or a missing prerequisite.


Step 3: Run the stranger test on a clean machine (20 min)


The person least able to judge a README is the person who wrote it, because they fill in the gaps without noticing. Ask someone who has never run the project to follow the README exactly, on a clean environment, while you watch and say nothing. Write down every point where they hesitate, guess, or ask a question.


Tom Preston-Werner's 2010 argument for "Readme Driven Development" was to write the README before the code, because "until you've written about your software, you have no idea what you'll be coding". The stranger test is the same idea applied afterwards: it finds the gap between what the software does and what you think it does.


Test you can run: time the stranger from a fresh checkout to a running project. Then fix every hesitation point and run it again with a different person. The second run should be faster and quieter.


Step 4: Make the quick start executable and check it in CI (20 min)


Docs rot for the same reason untested code breaks: nothing fails when they go wrong. The fix is the same too. Make the quick start runnable by a machine, and run it on every change.


There are several ways to do this. The simplest is to keep the setup commands in a script, such as make setup or ./scripts/bootstrap.sh, have the README tell people to run that script, and have CI run the same script in a clean container. The README then can't drift from the commands, because the commands live in one place and CI executes them. Some teams go further and extract code blocks from the README and execute them, which catches drift in the prose as well.


Test you can run: add a CI job that runs your quick start in a fresh container and fails the build if it doesn't complete. If you can't make that job pass today, your README is already wrong.


Step 5: Give every section an owner and a trigger (10 min)


Sections that CI can't check, such as architecture notes and contribution guidelines, need a different safeguard: a reason for someone to look at them. Add a line to your pull request template: "Does this change how the project is set up, configured or run? Update the README in this PR." Then make the README a file that reviewers expect to see touched when setup changes.


For sections that describe something owned by another team, such as a shared database or an internal platform, link to that team's documentation instead of copying it. A copy is a second version that will drift.


Test you can run: look at the last ten pull requests that changed configuration, dependencies or setup scripts. How many also changed the README? Any that didn't are places where the README may now be wrong.


Step 6: Review the README on a schedule as well (5 min)


Some drift has no pull request to catch it: a dependency that disappears upstream, an internal URL that moves, a team that changes its name. Put a short README check on the team's calendar every quarter: one person follows the quick start on a clean environment and fixes what has broken.


Test you can run: pick a README nobody has touched in six months and follow it on a clean machine. Count the steps that no longer work. That number tells you how often to schedule the check.


Worked example (composite)


A composite scenario, not a real company or service.


The logistics company in the opening had eleven services with READMEs. After the contractor's lost Monday, a senior engineer ran the stranger test on three of them, using new joiners from that month's intake.


The results were consistent. On average, each README had four steps that no longer worked as written, and every one of the failures traced back to a change in setup that hadn't touched the README: a renamed environment variable, a new required service, a dependency pinned in the build file but not in the instructions. The architecture sections were mostly fine. The quick starts were the problem.


The team moved each service's setup into a single bootstrap script, rewrote the quick starts to call that script, and added a CI job that ran it in a fresh container on every pull request. Two of the eleven jobs failed on the first run, which confirmed that those READMEs had been broken for months without anyone noticing.


The team kept a rough record: the next intake of new joiners reached a running service in under an hour, against most of a day for the previous intake. That was the team's own observation, not a controlled measurement, but the change in how often new joiners asked "how do I start this?" in the team channel was hard to miss.


Trade-offs to make deliberately


Choice

You gain

You risk

Short README with links

Newcomers find the first hour quickly

More documents to maintain and link

Everything in the README

One place to look

The quick start gets buried and goes unread

Quick start checked in CI

Drift fails the build instead of a new joiner

Effort to build and maintain the job

Stranger test with a real person

Finds gaps no script can

Takes someone's time

Copy other teams' docs in

Self-contained README

A second version that drifts


Common failure modes


  • Accurate on day one, wrong by day ninety. Nothing checks it, so nobody knows.

  • Written by the expert, for the expert. Gaps are invisible to the person who wrote it.

  • Four kinds of document in one page. The first-hour path disappears under reference material.

  • Troubleshooting at the end. The fix for step three is two screens away from step three.

  • Copied documentation. It drifts from the original and nobody owns the difference.


Final takeaway


A README is a promise about how to get started, and promises in software break silently unless something checks them. Keep the README focused on the first hour, run the stranger test, and put the quick start where CI can execute it. Your next action: this week, run your quick start in a fresh container. If it fails, fix it and add the CI job; if it passes, ask a stranger to follow it and watch where they hesitate.


Sources




Continue the Technical Writing for Engineers path



bottom of page