Technical Writing

Write for humans and machines. Every sentence earns its place or gets cut.

Core Principles

Lead with the point. First sentence = the takeaway. Context comes after, if needed.

One idea per unit. One point per sentence. One topic per paragraph. One concern per section.

Concrete over abstract. Name the thing. Show the example. Skip the preamble.

Active voice, imperative mood. "Add retry logic" not "Retry logic should be added" or "Added retry logic."

No filler words. Cut: "basically", "simply", "just", "in order to", "it should be noted that", "as mentioned above", "please note that", "going forward". If removing a word doesn't change the meaning, remove it.

No hedging unless uncertainty is the point. Say "This will break X" not "This could potentially have an impact on X."

Prefer short words. "use" over "utilize", "start" over "initialize", "show" over "indicate", "about" over "approximately."

Format: Git Commits

Structure:

<type>: <what changed>

<why it changed — optional, only if non-obvious>

Types: feat, fix, refactor, docs, test, chore, perf, ci

Rules:

Subject line under 72 characters
Imperative mood: "Add X" not "Added X" or "Adds X"
No period at end of subject
Body explains why, not what — the diff shows what
Reference issue numbers when relevant: Fixes #42

Good:

feat: add rate limiting to /api/upload

Prevents abuse from automated clients. Limits to 100 req/min
per API key. Returns 429 with Retry-After header.

Fixes #187

Bad:

Updated the upload endpoint to add some rate limiting functionality
so that we can prevent potential abuse issues going forward

Format: GitHub Issues

Bug Reports

## Problem
<What's broken — one sentence>

## Steps to Reproduce
1. <Exact steps>
2. <No ambiguity>

## Expected
<What should happen>

## Actual
<What happens instead>

## Context
- Version/commit: <hash or version>
- Environment: <OS, browser, runtime>
- Logs/screenshots: <if relevant>

Feature Requests

## Problem
<What user need is unmet — not the solution, the problem>

## Proposed Solution
<How to solve it — be specific>

## Alternatives Considered
<What else you evaluated and why it lost>

## Scope
<What's in, what's explicitly out>

Format: PRD (Product Requirements Document)

# <Feature Name>

## Problem
<Who has this problem. What they can't do. Why it matters now.>

## Solution
<What we're building. 2-3 sentences max.>

## Requirements

### Must Have
- <Requirement — testable, unambiguous>
- <Each one starts with a verb>

### Nice to Have
- <Lower priority items>

### Out of Scope
- <Explicitly excluded to prevent scope creep>

## Success Criteria
- <Measurable outcome>
- <How we know this worked>

## Technical Notes
<Constraints, dependencies, migration concerns — only if relevant>

## Open Questions
- <Unresolved decisions, with owners and deadlines>

Rules:

Requirements are testable. "Fast" is not a requirement. "Page loads in < 200ms at p95" is.
Each requirement starts with a verb: "Support", "Display", "Validate", "Allow".
Success criteria are measurable. If you can't measure it, sharpen it.
Open questions have owners. Unowned questions don't get answered.

Format: Technical Specs / Design Docs

# <Title>

## Context
<Why this doc exists. What decision or system it describes. 2-3 sentences.>

## Design

### Architecture
<How it works. Diagrams welcome, walls of text not.>

### Data Model
<Schema changes, new entities, relationships.>

### API
<Endpoints, contracts, examples.>

## Tradeoffs
<What you chose and what you gave up. Be honest about costs.>

## Risks
<What could go wrong. What's the mitigation.>

Format: Inline Code Comments

Only comment why, never what. The code says what.

Good:

// Retry 3x because the payment API returns transient 503s under load

Bad:

// Call the payment API with retries

Don't comment:

// Increment counter
count += 1

Format: PR Descriptions

## What
<One sentence — what this PR does>

## Why
<Motivation — link to issue if applicable>

## How
<Brief summary of approach — not a line-by-line walkthrough>

## Testing
<How you verified this works>

Anti-Patterns

The Wall of Context. Three paragraphs of background before the point. Invert it. Point first, context if needed.

The Passive Report. "It was determined that the service should be restarted." By whom? Say who did what.

Weasel Words. "Some users", "significant impact", "may cause issues." Quantify or be specific.

Premature Abstraction. Don't generalize when a concrete example communicates faster.

The Apology Prefix. Don't start with "Sorry for the long message" — make the message shorter instead.

Redundant Structure. Don't add sections just because the template has them. Empty "Risks: None" sections waste attention. Omit sections that add nothing.

Editing Checklist

Before publishing, read it once and cut:

Sentences that repeat what another sentence already said
Adjectives and adverbs that don't change the meaning
Throat-clearing openers ("So basically...", "As you may know...")
Sections with no actionable content
Anything the reader already knows or can infer