Technical Writing

Writing changes what the reader thinks. Most readers skim. Frontload the point, omit what doesn't serve the decision, respect attention.

Goal: give the reader enough to (a) trust your judgment, (b) make a decision, or (c) take a specific action — nothing more.

The Three Laws

Law 1 — Lead with the point. First sentence = conclusion, recommendation, or request. If they stop after one sentence, they should still know what you want.

Law 2 — Write less than you think. Cut context that doesn't change the decision. One sentence > one paragraph when both work.

Law 3 — Match depth to audience size. Slack to your team: one sentence. ADR for 3-5 reviewers: deep trade-offs. Company-wide: scannable in 30 seconds.

Slack/short messages: Skip ceremony. Open with the ask, include only context needed for the decision, close with explicit request. Don't run Steps 1-5.