Project documentation
Beginner
6 min read
The few documents every project needs — README, setup, decisions and runbooks — kept next to the code.
Why it matters
Code shows what the system does, not why or how to run it. A new teammate — or you in six months — needs the setup steps, the reasons behind decisions and what to do when something breaks.
Where it fits — Documentation applies across these stages
What you will learn
- Write a README that gets someone from clone to running.
- Record an important decision and its reasons in a short note.
- Keep a runbook for the tasks people do in production.
Before you start
- The software delivery lifecycle✓ Learned
Four documents that cover most needs
- README — what the project is, how to install, configure and run it, how to run the tests.
- Decision records — one short file per important decision: the context, the options, the choice and why.
- Runbooks — step-by-step instructions for operational tasks: deploy, roll back, restore a backup.
- Changelog — what changed in each version, written for the people who use it.
A README skeleton
README.md
# Project name
One sentence: what it does and for whom.
## Requirements
- PHP 8.4, Node.js 22, PostgreSQL 17
## Getting started
1. Copy .env.example to .env and fill in the values
2. Install dependencies
3. Run the app and open http://localhost:8000
## Tests
How to run them.
## Deployment
Link to the runbook.Tip: Keep docs in the repository, in plain Markdown. They are reviewed with the code and cannot drift into a wiki nobody updates.
Watch out: Never put passwords, tokens or real customer data in documentation. Describe where a secret comes from, not its value.
Official documentation and references
Documentation
- GitHub Docs — About READMEs ↗ Official · GitHub — Where GitHub shows a README and what it should contain.
Specifications
- Semantic Versioning ↗ Official · semver.org — The specification for version numbers like 1.4.2 that a changelog refers to.
Learn next
- Git basics ›✓ Learned
Related topics
- Architecture decisions and diagrams✓ Learned
- The software delivery lifecycle✓ Learned
- Configuration and secrets✓ Learned
Done with this topic?
Reviewed 2026-10-23. Links go to the official documentation unless marked otherwise.