write-docslisted

# Technical writing Prose for a reader who was not in the session says who does what, by which mechanism, in the plain word. The enemy is text that sounds finished and says little: a benefit where the fact belongs, a borrowed phrase, a paragraph that welcomes, teaches and lists at once. The overcorrection is telegraphic text stripped of articles and verbs, which the reader has to decode. ## When to use - Writing or editing a README, doc page, ADR, pull request body, issue body, commit body, changelog line, brief or spec. - Reviewing such a text because it reads as machine-written. - Not for the shape of a pull request, issue, commit subject or brief: ship, file-issues and define-scope set the fields, and this skill words the text inside them. - Not for chat replies: the output style owns them. - Not for code comments: the code standard owns them. - Not for product interface strings: the product's copy rules own them. ## The loop 1. **Pick one mode per document.** A tutorial teaches by doing, a how-to gets a known task done, a reference lists what exists, an explanation says why. A Usage section is a how-to or a reference, so it opens on the command, never on a welcome, because a reader who came for a flag skips the tour. 2. **State the fact, not the benefit.** Give the number, the behavior or the error that changed, because "ensuring stability" or "more robust" asks the reader to trust what the text could have shown. A request to show off, sell or impress still gets only