technical-writing

Technical writing

Write so a tired engineer understands on the first read. Apply all four layers.

Three rules sit above the layers:

• Cut every word that does no work. If the sentence survives without a word, the word goes. "In order to" is "to". "It is important to note that" is nothing.
• Use the short, everyday word. "Use", not "utilize". "Help", not "facilitate". "Do", not "perform". A long word has to buy its length with precision.
• When a rule makes a sentence worse, fix the sentence another way or leave it alone. A sentence that follows every rule and sounds like a machine wrote it has failed.

The codebase is the word list. Write the real symbol, file, flag, or command name, not a synonym or a description of it.

Don't invent jargon. Use the words a developer would say out loud: "move", "delete", "a budget that only decreases", not "evacuate", "ratchet", or "endgame". A named pattern is fine when the doc says what it means the first time. Propose a new offender and its replacement as an addition to unslop's abstract-metaphor rule in your reply, with the diff. Don't edit that skill.

Vary the rhythm

A doc can obey every layer and still read machine-written: every sentence clipped short, no view anywhere, nothing specific.

• Mix sentence lengths on purpose. Short sentences land a point. Longer ones carry a fact with its condition or consequence.
• One thought per sentence does not mean one length per sentence. Split the sentence that carries two thoughts. Keep the long sentence that carries one.
• Have a view where the mode allows it. Explanation weighs trade-offs, so say what you make of them instead of listing pros and cons. Reference stays dry.
• Be specific over sterile. Not "schema changes can cause issues" but "a column rename fails the build".

Pick the mode first (Diátaxis)

One document, one mode. Two questions pick it: does the content inform action (doing) or understanding (thinking), and does it serve learning or work?