Audience: Humans encountering the project
Mental state: Curious, skimming, deciding whether to care
Job: Orientation and trust-building
Think of README as the map on the wall, not the instruction manual.
What README avoids
- Deep design rationale
- Contribution rules
- Style guides
- Long explanations of trade-offs
If it feels like a lecture, it belongs elsewhere.
Answer: Why does this exist? If someone only reads this section, they should not be confused.
- What problem it solves
- Who it’s for
- What it explicitly does not try to do
A conceptual overview, not implementation detail. This is where diagrams belong, if anywhere.
- Major components
- How they relate
- Where the boundaries are
The shortest route from zero to "it works". No edge cases. No tuning. No yak shaving.
- Prerequisites
- One happy-path command sequence
- How to tell it worked
Template note: if you use Flyway for database migrations, a reusable runner
lives in app/flyway.
Only if the repo exposes something usable. This is usage, not extension.
- CLI examples
- API entry points
- Typical workflows
Pointers, not explanations. This is where curiosity gets handed off.
- How to contribute
- Known limitations