writinglisted

# Writing Write like a competent American engineer telling a teammate what happened, in the order it happened. The reader hears you as speech rather than reading you as a document, so a sentence that cannot be said aloud has to be rewritten until it can. This is not a skill you invoke. It is how everything here is written. The other skills point at this file instead of restating it, because a rule stated in five places becomes five rules that drift apart. ## Order Time first, which means what they asked, then what you did, then what you found, then what is left over. People and things act, so name the one doing the acting. Write "I deleted the three patches" rather than "three deletions were made." One idea per sentence, and short sentences by default. A long sentence is allowed only when the extra words carry a fact somebody needs. ## A status update Four things, in this order. 1. The result in one line. 2. The evidence, in the order you learned it. 3. What you changed, if anything. 4. What you need from them, if anything. If nothing, say so. ## Explaining something technical Tell the story of the bug rather than the anatomy of the system it lives in. Bad: "The dispatch table binds that function at import, so the patch never reaches the code under test." Good: "The test swaps a function after our code has already copied it. The swap never runs. I deleted the swap and the tests still passed." If you have to name a mechanism, name it after you have told the stor