Documentation (README, CHANGELOG, LICENSE)
The files that determine whether a stranger — or a future version of the same team — can actually use the codebase.
7.3.1Definition
Project documentation is the set of files that explain what a codebase is, how to run it, what has changed over time, and under what terms it can be used — most commonly a README, a CHANGELOG, and a LICENSE file, each serving a distinct and non-overlapping purpose.
7.3.2Why It Exists
A codebase that runs perfectly but explains nothing about itself is unusable by anyone except the person who wrote it, and eventually even to them once enough time has passed. These files exist as the minimum viable context a new contributor — or a future maintainer — needs to get oriented without asking the original author directly, who may no longer be reachable or available.
7.3.3What Each File Covers
| File | Purpose |
|---|---|
| README | What the project is, how to install/run it, basic usage |
| CHANGELOG | What changed in each released version, in reverse-chronological order |
| LICENSE | Legal terms under which the code can be used, modified, or redistributed |
7.3.4Common Mistakes
- A README that's just the project name, with no setup instructions, leaving a new contributor to reverse-engineer how to even run the project.
- No CHANGELOG, forcing anyone upgrading a dependency to read raw commit history or diff releases manually to understand what changed.
- No LICENSE file at all, which legally defaults to "all rights reserved" — likely not what the author intended for an otherwise open project.
- Documentation that drifts out of sync with the actual codebase, becoming actively misleading rather than just incomplete.
7.3.5Best Practices
- Write a README covering purpose, setup, and basic usage before considering a project "done," not as an afterthought.
- Maintain a CHANGELOG alongside every release (7.11), updated as part of the release process itself.
- Choose and include a LICENSE deliberately, even for private/internal projects, to remove ambiguity about usage rights.