Writing documentation people actually use

Documentation is the highest-leverage contribution most projects will accept, and the one most people write badly — because they write what they know instead of what the reader needs.

The rules I write docs by

Task-first, not feature-first. "How to import your existing data" beats "Data import functionality." Readers arrive with a job; organise around jobs, not around your API's table of contents.

Answer the next question. After each section, I ask: what will the reader now want to know? If the doc doesn't answer it, they leave for a search engine — and possibly for another project.

Test docs like code. Every command in the docs runs on a clean setup before shipping. "It worked when I wrote it" is how broken instructions ship. Docs with a tested paste-path are a feature; docs without are a liability wearing helpfulness.

Say what it doesn't do. A "Limitations" section earns trust the way error messages earn trust: by telling the truth at the moment of maximum need.

The giveaway of bad docs

Adjectives. Documentation that says "powerful," "simple," and "elegant" is selling. Documentation that shows the three commands and one honest caveat is helping. I try to write only the second kind.