Rule 1: Know Your Audience
Before typing a single word, ask: "Who is reading this, and what do they need to do after reading it?"
The same system may need three completely different documents:
| Audience | Context | What They Need |
|---|---|---|
| New Hire | Onboarding | Context, prerequisites, "why does this exist?" |
| SRE at 3 AM | Active incident | Checklists, exact commands, no theory |
| CTO / Stakeholder | Architecture review | High-level design, business value, trade-offs |
Writing a single document that tries to serve all three audiences serves none of them. Separate your content by audience and purpose.
Rule 2: Active Voice vs. Passive Voice
Passive voice hides the actor — the person or system responsible for an action — and introduces ambiguity. Active voice is direct and unambiguous.
| Voice | Example | Problem |
|---|---|---|
| Passive | "The database should be backed up." | By whom? When? Automatically or manually? |
| Active | "The backup script runs daily at 02:00 UTC." | Clear actor, clear schedule. |
| Imperative | "Run ./backup.sh before deploying." |
Direct instruction to the reader. |
For procedural documentation (how-tos, runbooks), use imperative mood — the command form. "Install the package." "Set the environment variable." "Restart the service." This is how your shell works, and it is how your documentation should work.
Rule 3: One Idea Per Sentence
Engineers are trained to hold complex, nested logic in their heads. This is a superpower for coding and a liability for writing. Break compound sentences apart.
Bad:
"When the pod fails, if the retry count is greater than 5, the controller, which is watching the state, sends an alert to PagerDuty, unless it is a weekend."
Good:
"The controller continuously watches pod state. If a pod fails more than 5 times, the controller sends an alert to PagerDuty. Alerts are suppressed on weekends."
The second version is easier to scan, easier to translate, and easier to update when the retry threshold changes.
Rule 4: Be Specific — Eliminate Vague Words
Vague words force the reader to make assumptions. In operational contexts, wrong assumptions cause incidents.
| Vague | Specific |
|---|---|
| "Wait for a while." | "Wait 60 seconds." |
| "Several replicas" | "3 replicas" |
| "A large file" | "Files larger than 100 MB" |
| "The config file" | "/etc/app/config.yaml" |
| "Restart the service" | "sudo systemctl restart app" |
Rule 5: Use Structure to Aid Scanning
Readers of technical documentation rarely read linearly. They scan for the section they need. Use these structural tools:
- Headers to divide sections (H2 for major sections, H3 for subsections).
- Numbered lists for sequential steps where order matters.
- Bullet lists for unordered items (prerequisites, options, features).
- Code blocks for every command, file path, and configuration snippet — never inline prose.
- Bold text for key terms on first use and critical warnings.
Interviewers for Staff+ and Platform Engineering roles often ask: "How do you ensure documentation quality across a team?" A strong answer covers three layers: (1) structural standards enforced by linters in CI (e.g., markdownlint), (2) process standards enforced by PR review checklists, and (3) cultural standards enforced by making documentation a first-class deliverable — not an afterthought. Mentioning that you treat docs debt the same as tech debt signals seniority.