Write a README That Helps Future You Ship. A Build Next Stack field guide for learners shipping small projects.
README job one: boot the project in fifteen minutes
A README is not a brochure. For solo side projects it is the onboarding doc for the person who forgot the stack—still you, but with zero context loaded. Lead with a Quick start block that a stranger on a new laptop could follow: clone, install runtime version, copy env template, one command to run, one command to test.
Casey rebuilt a markdown notes API twice because the README said install deps without pinning Node. The second rebuild added:
- Prerequisites — Node 20.x, Docker optional for Postgres
- Setup — cp .env.example .env, fill three keys linked below
- Run — npm run dev → http://localhost:5173
- Test — npm test — expect 12 passing
If quick start fails, everything below is decoration. Time yourself monthly; over fifteen minutes means the README is lying.
Document decisions, not just commands
Future you needs the why behind weird folders. Casey keeps a Decisions section with dated bullets: 2026-03 — SQLite for local, Postgres in prod because host offers managed DB free tier. That sentence prevents a Saturday rewrite to flat files because you forgot the constraint.
Link to issues or ADR files if you write them; one README paragraph beats no trail. When you reverse a decision, strike through the old bullet and add the new one—history visible, not deleted.
Avoid essay length. Three to five decisions cover most small projects. If the list grows past ten, extract to docs/decisions.md and link once.
Environment variables with copy-paste examples
List every env var the app reads, with example values and where to obtain real ones. Table format works:
- DATABASE_URL — local: sqlite:./dev.db; prod: host dashboard → Connections
- SESSION_SECRET — generate: openssl rand -hex 32
- SENTRY_DSN — optional; leave empty to disable
Mark which vars are required vs optional. Solo projects fail at 9 p.m. because .env.example omitted a feature flag you added in code but never documented.
When you add a new env var in code, update the README in the same commit. Same-commit rule beats a linter you will not configure for a hobby repo.
Troubleshooting for the errors you hit twice
Maintain a Troubleshooting section only for errors that recurred. First occurrence goes in an issue; second occurrence earns a README bullet with the fix that worked.
Casey’s entries look like:
- EADDRINUSE on 5173 — kill stale Vite: npx kill-port 5173
- Prisma migrate drift — reset local only: npx prisma migrate reset (destroys data)
- Sharp install fails on Apple Silicon — npm rebuild sharp after Rosetta Node mistake
This section rots if you treat it as FAQ cosplay. Prune bullets you have not seen in a year. A short honest list beats a graveyard of maybe fixes.
Scope and non-goals prevent feature creep
Write What this is / What this is not in plain language. Personal bookmark sync for one user—not multi-tenant SaaS. That line saves weeks when you are tempted to add teams because a tutorial showed RBAC.
Include a Current limitations list you are willing to ship with: no offline mode, imports capped at 500 rows, admin UI missing. Users and future you calibrate expectations. Limitations removed belong in changelog, not silently fixed without note.
Non-goals are permission to say no to your own brain at 1 a.m.
Deploy and rollback in five lines
Solo READMEs often stop at local dev. Add Deploy with host name, branch rule, and the one command or button sequence. Add Rollback with the previous tag or host snapshot step.
Example:
- Deploy — push main; Render auto-builds; watch Logs tab for migrate step
- Rollback — Render → Deploys → activate previous; run npm run migrate:down if schema changed
If deploy is manual, screenshot the click path once and link the image in docs/. Panic at deploy time is not when you want to discover the host moved a menu.
README maintenance as part of shipping
Casey adds a checkbox to every release PR—yes, solo PR from branch to main: README quick start verified on clean clone. False checks hurt less than fantasy docs.
Once a quarter, ask someone literate in computers but unfamiliar with the project to follow quick start while you watch silently. Every stumble becomes a README edit, not a joke about bad memory.
The README ships with the feature. Treat it as code that breaks builds when wrong—because it breaks weekends.
Casey keeps a Last verified date at the top of quick start—updated only after a clean clone test passes. Stale dates are honest signals; missing dates pretend docs always work.
Screenshots and paths that rot slowly
UI screenshots in READMEs age fast. Casey prefers text paths and menu names over pretty images: Settings → Import → CSV. When a screenshot helps—complex admin panel—store in docs/img/ with filename containing date import-flow-2026-05.png so stale images embarrass visibly.
Link to live demo only if you will maintain it; broken demo links hurt trust more than no demo. Portfolio README can say Demo offline for maintenance—see demo-script.md for local recording instead of 404.
Architecture diagrams belong in docs/ when they exceed one screen; README links once. Solo projects rarely need enterprise diagram standards—a box arrow box sketch with labels beats no diagram.
When renaming folders, grep README for old paths in the same commit. Broken path links are the most common README failure after dependency upgrades.
Field example: Casey resets a neglected README in one hour
Casey’s bookmark API README had drifted six months. One-hour reset plan:
- Clone to temp directory; note every failure until quick start works.
- Rewrite quick start only—delete badge clutter and outdated roadmap.
- Add env table from grep of process.env or equivalent in code.
- Move old tutorial prose to docs/archive/ linked once as historical context.
Result: README under two hundred lines, quick start verified, decisions section with three bullets. Feature marketing returned only after boot path was trustworthy again.
Casey schedules README reset quarterly on calendar—same dignity as dependency updates. Preventive honesty beats apologetic issues from new contributors who could not boot the project.
Add one section before the next feature
Open your side project README now. If quick start is missing or older than your last dependency bump, fix that before writing new code. One honest fifteen-minute path beats a logo badge wall.
Future you does not need motivation quotes—you need copy-paste commands, env tables, and three decisions that explain the weird parts.
Ship README updates in the same commit as the behavior they describe. Documentation lag is how solo projects become personal folklore.