technical-writing

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.

---

STEP 1 — Classify the Document

If user provides a template: Preserve its structure exactly. Apply Three Laws within each section. Flag gaps as suggestions.

Otherwise, classify:

Type	Purpose	Audience	Length
RFC / Design Doc	Propose approach, surface trade-offs, get alignment	5-20 engineers	2-8 pages
ADR	Record decision + rationale for future	3-10 now, unlimited later	0.5-2 pages
One-Pager	Pitch project, get buy-in/resources	Leadership + stakeholders	1 page strict
Runbook	Enable someone to perform unfamiliar task	On-call engineers	Step-by-step
Postmortem	Learn from incident, prevent recurrence	Broad eng org	1-3 pages
Announcement	Inform about change, decision, event	Team → org → company	3-10 sentences
PR Description	Give reviewers context for review	1-5 reviewers	5-20 lines
Slack / Async	Get a decision or response quickly	1-20 people	1-5 sentences

If it doesn't fit: ask "What decision or action should the reader take?" — answer determines structure.

STEP 2 — Audience Brief

Who reads this: [specific roles, not "engineers"]
What they already know: [shared context — don't repeat]
What decision they'll make: [approve? understand? execute?]
What they'll do after: [specific action]
Attention budget: [seconds? minutes? deep read?]

If you can't fill this in, the document will fail.

STEP 3 — Write the Key Sentence

One sentence capturing the entire document. Must: state the conclusion (not topic), be understandable with zero context, survive being the only thing read.

"We should use Redis for session caching" — not "This document evaluates caching options."

This becomes the opening line / TL;DR / subject prefix. If you can't write it, you haven't thought clearly enough.

---

STEP 4 — Draft Using Template

RFC / Design Doc

# [Key Sentence as Title]
**Author(s)**: | **Approvers**: | **Status**: Draft | In Review | Approved | Superseded
**Date**: | **Last updated**:

## TL;DR
[Key Sentence expanded to 2-3 sentences.]

## Background
[Objective facts only. Current state, problem, prior art. Write for someone who has never seen this codebase.]

## Goals and Non-Goals
### Goals
- [Specific, measurable. Tied to OKRs where relevant.]
### Non-Goals
- [Explicitly excluded scope. Prevents scope creep.]

## Proposed Design
[High-level overview, then detail. Focus on trade-offs, not implementation steps.
If writing steps with no trade-off discussion, you don't need an RFC.]

## Alternatives Considered
**First alternative MUST be "Do Nothing".** An RFC that can't explain why "do nothing" is worse hasn't justified its existence.

Each alternative: what it is, trade-offs, why not selected.

## Cross-Cutting Concerns
[Security, privacy, observability, accessibility, cost. "N/A" shows you considered it.]

## Risks and Mitigations
[What could go wrong? Rollback plan? Be specific.]

## Open Questions
[Questions for reviewers to contribute knowledge, not just opinions.]

If no real alternatives or trade-offs, write an ADR instead.

ADR

# ADR-[N]: [Decision — verb phrase]
**Status**: Proposed | Accepted | Deprecated | Superseded by ADR-[N]
**Date**: | **Deciders**:

## Context
[Situation, constraints, forces. Write for someone who has never seen this codebase.]

## Decision
[1-2 sentences. "We will use PostgreSQL for user data storage."]

## Consequences
### Positive — [what becomes easier]
### Negative — [what becomes harder — be honest]
### Neutral — [what changes without clear valence]

Should take 15-30 minutes. Hours = need an RFC or over-detailing.

One-Pager

# [Project]: [Key Sentence]
**Author**: | **Date**: | **Ask**: [approval, resources, headcount, time]

## Problem — [2-3 sentences. Quantify impact.]
## Proposal — [3-5 sentences. Highest-level approach.]
## Expected Impact — [Quantified. Tied to metrics audience cares about.]
## Cost — [Time, people, infrastructure. Be specific.]
## Risks — [Top 2-3, one sentence each with mitigation.]
## Timeline — [Key milestones only. 3-5 lines.]

Reader should finish thinking "worth doing" or "not worth doing" — never "I need more information."

Runbook

# Runbook: [Action phrase]
**Last verified**: [date] | **Owner**: [team/person] | **Est. time**: [duration]

## When to Use
[Specific triggers — alert names, dashboard thresholds.]

## Prerequisites
[Access, tools, context needed.]

## Steps
### 1. [Action verb] — [what and why]
`[exact command]`
Expected output: [what to see]
If this fails: [what to do instead]
[Repeat for each step.]

## Verification — [How to confirm it worked.]
## Rollback — [How to undo.]
## Escalation — [Who to contact. Slack, PagerDuty, phone.]

"Last verified" is the most important metadata. An untested runbook creates false confidence.

Postmortem

# Postmortem: [What happened — not why]
**Date**: | **Duration**: | **Severity**: | **Author**: | **Reviewers**:

## Summary — [3-5 sentences for someone uninvolved.]
## Timeline — [Time (UTC) | Event]
## Root Cause — [Specific. "Migration added index on 500M rows without CONCURRENTLY" not "configuration error."]
## Impact — [Quantified: users, revenue, SLA, data integrity.]
## What Went Well
## What Went Poorly
## Action Items

| Action | Owner | Priority | Due Date |
|--------|-------|----------|----------|

## Lessons Learned — [1-3 broader lessons.]

Action item rules:

• Verifiable: "Add alert when P99 > 3s for 5min" not "Improve monitoring"
• Owned: person (not team) + priority + due date. Missing any = aspirational.
• No exploratory items: "Investigate..." is not an action. Commit to findings by a date, or drop it.
• 3-5 items. More than 7 = not prioritized.

Announcement

**Subject**: [Key Sentence — what changed + what reader should do]

[Key Sentence expanded. 1-2 sentences.]
**What's changing**: [2-3 sentences]
**Why**: [1-2 sentences. Connect to a goal the reader cares about.]
**What you need to do**: [Specific action, or "Nothing — informational"]
**Timeline**: [When this takes effect]
**Questions?**: [Where to ask]

If longer than 10 sentences, link a document instead of inlining.

PR Description

## What — [1-2 sentences. The change.]
## Why — [1-2 sentences. Link to issue/ticket.]
## How — [Approach. Only what reviewer needs.]
## Testing — [How tested. What to verify.]
## Risks / Rollback — [Only if risky.]

Slack / Async

[What you need.]
[1-2 sentences context — only what's needed for the decision.]
[Explicit ask — "Can you approve by EOD?" / "Which option: A or B?"]

Never start with context before stating what you need.

---

STEP 5 — Review Checks

• First-Sentence Test: Read only first sentences of each section. Does the doc still make sense?
• So-What Test: Every paragraph — "what should the reader do with this?" If nothing, cut it.
• Stranger Test: Could someone who just joined understand this?
• Compression Test: Can you cut 30%? Almost always yes on first draft.
• Decision Test: After reading, does the reader know what to decide or do?

---

Calibration

1. Structure ≠ thinking. Perfect RFC format with no trade-off analysis wastes everyone's time.
2. Don't write what should be a conversation. 2-3 people + uncontroversial = Slack or call.
3. Every doc has a shelf life. Write for when it'll be read (RFC: review, ADR: 6 months later, runbook: 3am).
4. The writing is the thinking. Can't write the Key Sentence = haven't thought clearly enough.
5. Adapt to the org. Templates are starting points. Principles apply regardless of format.