How to Write Documentation People Actually Read
Documentation is the easiest way to start contributing. Learn what a README, CONTRIBUTING and CHANGELOG need, and the writing style that keeps projects usable.
Admin
FOSS Andhra community volunteer writing about free and open source software, education and developer tools from Andhra Pradesh.
Good documentation is what separates a project people can actually use from one they quietly abandon. It is also the most accessible way to start contributing: maintainers usually merge a clear documentation improvement much faster than a risky code change.
The documents every project needs
1. README
The front page of your repository. It should answer, quickly:
- What the project does, in one or two sentences
- A screenshot or a short demo, if there is an interface
- Installation steps for the most common case
- A minimal usage example that actually works
- Where to get help
2. CONTRIBUTING
How to take part: how to set up a development environment, the coding style, how to submit a pull request, and what reviewers expect. When people know the expectations, reviews get faster and friendlier.
3. CHANGELOG
A short file noting what changed in each version. It does not need every commit, only what users care about.
Writing style that works
- Write for someone new to the project, not new to software, and not for the author.
- Show, do not only tell. A copy-pasteable command beats a paragraph of description.
- Test your code samples. Instructions that bit-rot are worse than no instructions.
- Use consistent terms. If you call it a project in one file, do not call it an app in another.
- Separate how from why. Put the steps first, the background and explanation afterwards.
Keeping documentation healthy
Documentation is not written once. Read your own README after every major change and remove mentions of features that no longer exist. Keep sentences short and check links regularly, because they rot fast.
Contribute through documentation
Pick a project you already use and read its docs with fresh eyes. Does the installation actually work on your machine? Is any term confusing? Is a sample broken? Each of those is a real issue you can fix, and a real contribution. Our guide to making your first contribution covers the workflow from fork to pull request.
When you document your own project, give it a proper license; our licensing explainer covers MIT, Apache and GPL. To sharpen your writing with feedback from others, join FOSStar and share your work at our events.