The 5-Minute README Test

A simple test for whether a project is actually documented or just has a README file. Plus the 5 things every README needs to pass.

The testHand a stranger your project's README. Wait 5 minutes. Walk away. If they can get a working copy of the project on their own machine in those 5 minutes, the README passes. If they cannot, the README fails. The 5 minutes is non-negotiable. The stranger is non-negotiable. The stranger must be someone who has never seen the project before.I have been running this test on my own projects for about three years, and the failure rate is embarrassing. Of the roughly 30 projects I have tested, 4 passed on the first try. The other 26 needed at least one round of fixes, and 11 needed two or more. The fixes were not deep rewrites. They were small things: a missing dependency, an unclear command, a config file that the README forgot to mention existed.The 5-minute test is the only documentation test I trust. Other tests (e.g. "is the README long enough," "does it have a section on contributing," "does it have badges") are theater. The only test that matters is whether a stranger can use the project from the README alone.The 5 things every README needsHere is the list. Every project I have tested, that passed, had all five of these. Every project that failed was missing at least one.What it is, in one sentence. Not a paragraph. Not three sentences. One sentence. If a stranger reads only the first line of the README and walks away, they should still be able to tell anyone else what the project is. ("A blog writing factory that turns a one-line seed into a publish-ready blog post." "A weekend backup script with rotation and logging." "A static site generator for people who want a site, not a framework.")What it does, in three bullet points. Below the one-sentence summary, three concrete bullets. Each bullet is something the project actually does, not a feature category. ("Writes a backup tarball to disk." "Rotates old backups after 30 days." "Sends an email alert if the job fails." Not "Backup features.") The bullets are what the one-sentence summary is, made concrete.How to install it, in three commands. Copy-paste runnable. Three commands, no more. If your install is more than three commands, the install is the bug; rewrite it. The three commands should be exactly the three commands a stranger would type, in the order they would type them.How to use it, in one example. One example. Real. Runnable. Produces output. If the README has 10 examples, the README fails (the project is too complex for a README; it needs a tutorial). If the README has zero examples, the README fails (the install command ran but the stranger does not know what to do next). One example is the sweet spot.Where to get help, with the response time. A link to the issue tracker, a Discord, an email, an FAQ, whatever. The point is: if the stranger gets stuck, they know where to go. The response time is the part most READMEs leave out, and it is the part that makes the difference between "I will use this" and "I will abandon this and find another tool." ("GitHub issues, best-effort, I usually reply within 48 hours on weekdays." is a real answer.)That is the list. Five things. Each one is one section of the README. The order matters: summary first, install third, example fourth, help fifth. A stranger will read the README in that order, and the README should be optimized for the order a stranger reads it in.What the test catchesHere is what the 5-minute test has caught in my own projects, with examples. Each one is a real fix I made after watching a stranger fail to use the project.Missing system dependencies. "Install with pip install -r requirements.txt" assumed the system had Python, pip, and a C compiler. None of those were in the README. The stranger installed pip and got a build error. Fix: added "Requires Python 3.10 or later. On Mac, brew install python. On Ubuntu, sudo apt install python3 python3-pip." The test passes now.Wrong working directory. "Run python factory.py" assumed the stranger was in the project root. The stranger was not. Fix: added "cd factory" before the run command. The test passes now.Missing config file. "Run python factory.py" assumed a config file existed at ./config.toml. The stranger did not have one, because the README did not mention that the config was a separate file. Fix: the README now has a section called "First time setup" that walks the stranger through creating the config.Vague "run the example" instruction. "To run the example, see examples/" assumed the stranger would know to look in the examples/ directory, find the example file, and run it. The stranger did not. Fix: the README now has a "Quickstart" section that says, in full, "Run python examples/hello.py and you should see 'Hello, world' printed to your terminal." The test passes now.Each of those is a 2-line fix that took 20 minutes to identify. Each of them was invisible to me, the author, because I had the project in my head. The stranger did not. The 5-minute test is the cheapest way I know to find the things the author has forgotten the reader does not know.What it does not doThe 5-minute test is not a substitute for a tutorial, a docs site, or a video. It is a floor. If the README does not pass the 5-minute test, the project is not ready to share. If the README does pass, the project is ready to share, and the docs site (if you have one) is a bonus, not a requirement.It also does not work for projects where "use it" requires a paid API key, a managed account, or a non-trivial setup. For those projects, the test becomes 15 minutes or 30 minutes, and the README has to include the setup steps. The 5-minute number is for projects that a stranger can run from a fresh laptop in 5 minutes. If that is not the project, the test is not the right test, and the README has different requirements.How to run the test on your own projectPick a person who has never seen the project. Send them the link to the repo, with no other context. Tell them "Try to get this running. You have 5 minutes. I am going to step away." Walk away. Do not answer questions during the test. If they finish in under 5 minutes, the README passes. If they do not finish, ask them where they got stuck. Fix the README. Run the test again. Repeat until the README passes.I do this with a friend who writes code but has never seen my projects. He is my README test. He has saved me from shipping at least four READMEs that would have lost me users in the first five minutes.The honest partThe 5-minute test is annoying. It requires another person. It requires patience. It is much easier to write a long README that "covers everything" and call it documented. The long README is not documented. It is a wall of text that no one reads. The 5-minute test is the only test that matters, and it is the one most projects skip.If you do not have a friend to test on, you can approximate the test by waiting 6 months, then trying to install your own project from your own README. The result is the same, just slower. I have done both. The friend is faster, and the failure rate is more honest, because the friend is not invested in the project passing.Want a prompt pack that uses this test?The Blog Writing Factory includes a "voice prompt" that uses the same pattern: anchor to a sample, test against a real example, ship only what passes. The pack is the system. The 5-minute test is the audit.Buy on Gumroad. $14

Send me the rough edges if you try it. I read every message.