Technical Writing

Core principle: Writing isn't about explaining what you think. It's about changing what the reader thinks. Almost none of your readers will pay full attention — they'll read the first sentence, skim the next, and either skim the rest or stop entirely. Every technical document must therefore frontload its point, omit what doesn't serve the reader's decision, and respect the reader's time as the scarcest resource.

The goal is not to transplant your understanding into someone else's head. The goal is to give the reader enough context to either (a) trust your judgment, (b) make a decision, or (c) take a specific action — and nothing more.

The Three Laws of Technical Writing

Every piece of technical writing, regardless of format, must obey these laws in order:

Law 1 — Lead with the point. The first sentence should contain your conclusion, recommendation, or request. If a reader stops after one sentence, they should still know what you want. This applies to Slack messages, emails, RFCs, and design docs equally.

Law 2 — Write less than you think you should. The biggest mistake engineers make is trying to communicate in too much detail and ending up communicating nothing at all. Omit subtle details. Cut context that doesn't change the reader's decision. If you can say it in one sentence, do that.

Law 3 — Match depth to audience size. A Slack message to your team can be one sentence. An ADR for 3-5 reviewers can go deep into trade-offs. A company-wide announcement should be scannable in 30 seconds. The narrower the audience, the more detail is justified.

Quick-fire rule for Slack and short messages: If the user asks you to write a Slack message, async message, or any communication under 5 sentences — skip all ceremony. Apply the Three Laws directly: open with the ask, include only the context needed for the decision, close with an explicit request. Do not run the full Step 1-5 process. This is the highest-frequency use case and the one where the Three Laws have the most impact.