Documentation Skills
Documentation is the written knowledge that lets other people, and your future self, use, change and operate software. It ranges from a README and code comments to guides, decision records and runbooks.
Kinds of documentation
- The README says what the project is, how to install and run it, how to test it and where to find more. It is the front door.
- Tutorials and how-to guides give step-by-step help for learning or for a specific task.
- Reference is accurate lookup material such as API descriptions and configuration options.
- Explanation and decisions say why things are the way they are. Short architecture decision records (ADRs) capture the context and the choice.
- Runbooks say what to do when something breaks or a routine task must be performed.
- Code comments explain why; the code already says what. See Clean Code and Naming.
The Diataxis framework (linked below) keeps tutorials, how-to guides, reference and explanation apart, because mixing them makes pages confusing.
Keeping docs maintainable
- Keep docs next to the code, in the repository, so they change in the same pull request as the code. See Repository Structure.
- Write for a reader who is new. State prerequisites and expected results.
- Prefer short pages with one purpose and clear headings.
- Test your instructions on a clean machine, or have someone follow them.
- Avoid copying the same information in many places; link instead.
- Date or version anything that goes stale, and delete what is wrong.
Markdown in a nutshell
Markdown is plain text with light formatting symbols, used in READMEs, wikis and pull requests. Platforms add small differences, so check yours.
## Setup
1. Clone the repository.
2. Run `make install`.
| Option | Default |
|---|---|
| `PORT` | `8080` |
See [the contributing guide](CONTRIBUTING.md) for more.Use ## headings, - or 1. for lists, backticks for inline code, fenced blocks (three backticks, optionally with a language name) for longer code, and [text](url) for links.
A minimal README
Name and one-line purpose, prerequisites, setup, how to run, how to test, configuration, and where to ask for help. Keep it honest and short.
Try it
Choose a small project you know. Write a README with the sections above, then ask a colleague, or use a clean checkout, to follow it exactly. Fix every place they get stuck.
Common mistakes
- Copying the same information into many places instead of linking.
- Leaving stale or wrong docs in place.
- Writing instructions without testing them on a clean machine.
- Mixing tutorial, reference and explanation on one page.
Check yourself
- What belongs in a minimal README?
- How can you check that your setup instructions work?
- What does an architecture decision record capture?