A README succeeds when another person can understand the project and reproduce its expected result without reconstructing your memory. State what the project does, what it requires, how to install, run, test, and verify it, and where to get help.
Write for a defined reader
Name the reader and starting state:
These instructions are for a CS 101 student with Git and Python 3.13 installed who has cloned the repository but has not created the environment.
Do not assume “everyone knows” your operating system, runtime, working directory, environment variables, or expected output. State supported versions only when verified.
Use a reusable structure
# Project name
One-sentence purpose.
## Expected result
What the user should observe.
## Requirements
- Required tools and tested versions
- Accounts, permissions, or platform limits
## Get the project
Exact repository and starting-directory instructions.
## Install
Commands with explanations and expected evidence.
## Run
The smallest valid example and expected output.
## Test
Commands, scope, and what success means.
## Troubleshooting
Known evidence-based failures and checks.
## Data, privacy, and safety
Inputs that must not be committed or shared.
## Help and maintenance
Where to report problems and current maintenance status.
Add license and contribution information only when the project needs them and the owner has authority to provide them.
GitHub’s current README documentation lists purpose, usefulness, setup, help, and maintainers as common README information. It also documents repository-relative links, which help documentation move with the project.
Separate installation, running, and testing
Installation changes the environment. Running performs the project’s primary behavior. Testing checks expected behavior. Combining all three into one unexplained command makes failures harder to diagnose.
For every command, state:
- the required current directory;
- whether it changes files or installs software;
- placeholders the reader must replace;
- expected output or artifact; and
- a safe verification step.
Never include real tokens or passwords. Use an example environment file with obviously fake values and document secure configuration.
Verify from a clean context
The author already has hidden context: installed dependencies, cached files, shell settings, and remembered steps. Test the README in a fresh clone, container, virtual machine, or other safe clean environment appropriate for the project.
Follow only the written instructions. Record:
- the first ambiguous step;
- missing requirements;
- commands that depend on an unstated directory;
- output that differs from the README; and
- cleanup or recovery needs.
If another person tests, observe where the instructions fail without taking over their keyboard.
Keep claims and project state aligned
Update the README in the same logical change as interface, dependency, or setup changes. Do not claim support for a platform no one tested. Label planned features as planned.
A badge or passing workflow is supporting evidence, not a substitute for understandable local verification.
Common mistakes
- Starting with installation before explaining purpose.
- Writing “run the project” without the command and directory.
- Omitting tested versions.
- Copying terminal prompts into commands.
- Documenting a generated file but not its source.
- Including secrets in examples.
- Assuming a public repository grants a license.
Do this now
Start with one current project and one clean-start test. Expand the README only when that test exposes a missing instruction.
Copy the template into a safe project. Fill every relevant section, then test the instructions from a clean context. Revise the first point where written instructions and observed behavior differ.
For a large project, a guided chatbot interview can extract candidate answers from approved repository context and ask about missing sections. Verify every command and claim in the project itself.
Log what you learned
Record only:
- Result: What did the action produce?
- Evidence: What observation, test, or source supports that result?
- Next action or unresolved question: What should happen next?
The next series uses this documented technical foundation to make AI assistance support learning rather than replace it.