writing-documentationlisted

# Writing documentation Documentation that lies is worse than none: it costs the reader time and then costs them trust. Everything below follows from that. ## Write for someone at a specific moment Before writing, name the reader and what they are trying to do. Somebody installing this for the first time needs different words than somebody debugging it at midnight. A page that tries to serve both serves neither. Then answer their question in the first paragraph. Background, history and rationale go below, if at all. ## Get it from the code, not from the old docs Read the implementation. Run the command you are about to document and paste what it actually printed. Check the flag still exists, the default is still what the page claims, and the example still works. Copying a stale sentence forward is how documentation rots. If the code and the docs disagree, that is a finding — say which one you think is wrong rather than quietly picking one. ## Shape - Short sentences. Concrete nouns. Present tense. - One working example beats three paragraphs of description. Make it copy-pasteable and make it the simplest case, not the most impressive. - Say what something is for before how to use it. - Document the failure too: what the common error means and what to do about it. That is the paragraph people arrive from a search engine to find. - No marketing, no "simply", no "just". If a step is easy, it does not need saying; if it is not, the word is an insult. ## Keep it ne