Technical Writing

Rules:

• Quick Start must work on a fresh machine in under 5 minutes
• Every command must be copy-pasteable (no <placeholder> without explanation)
• Test the README by following it literally on a clean environment

Architecture Decision Record (ADR)

# ADR-{NNN}: {Decision Title}

## Status
Accepted | Superseded by ADR-{NNN} | Deprecated

## Context
What problem are we solving? What constraints exist?

## Decision
What did we decide and why?

## Alternatives Considered
| Option | Pros | Cons | Why Not |
|--------|------|------|---------|

## Consequences
What changes as a result? What new constraints are introduced?

Runbook/Playbook

# Runbook: {Incident Type}

## Symptoms
What does the user/monitor see?

## Impact
Who is affected? What's the blast radius?

## Diagnosis Steps
1. Check {metric/log/dashboard} — expected: {value}
2. Run `{command}` — look for {pattern}
3. ...

## Resolution Steps
1. {Step with exact command}
2. {Verification step}
3. ...

## Escalation
If not resolved in {time}, contact {team/person}.

## Post-Incident
- [ ] Update this runbook with new learnings
- [ ] File ticket for permanent fix

3. Writing Principles

Know Your Reader

The Inverted Pyramid

Put the most important information first. Readers scan, they don't read.

┌─────────────────────────┐
│    What + Why (lead)    │  ← First paragraph answers the key question
├─────────────────────────┤
│  How (details)          │  ← Supporting details, steps, configuration
├─────────────────────────┤
│  Reference (appendix)   │  ← Edge cases, history, alternatives
└─────────────────────────┘

Plain Language Rules

4. Code Examples in Documentation

Rules for Code Samples

# ✅ GOOD: Complete, runnable example with imports
from datetime import datetime
from myapp.models import User

def create_user(name: str, email: str) -> User:
    """Create a user and return the saved instance."""
    user = User(name=name, email=email, created_at=datetime.now())
    user.save()
    return user

# Usage
user = create_user("Alice", "[email protected]")
print(user.id)  # => "usr_abc123"

# ❌ BAD: Incomplete snippet, no context
def create_user(name, email):
    user = User(name=name, email=email)  # What is User? Where is it imported?
    user.save()  # Does this return something?

Rules:

• Include imports
• Show expected output in comments
• Use realistic data (not "foo", "bar", "test")
• Every example must be copy-pasteable and runnable

5. Diagrams

Use diagrams for architecture, data flow, and sequences. Text alone fails for spatial relationships.

When to Use Each Type

Diagram Rules

• Label every arrow (what data flows, what triggers the transition)
• Include a legend if using color coding
• Keep to 7±2 elements — decompose larger diagrams
• Store diagrams as code (Mermaid, PlantUML) for version control

6. API Documentation

Endpoint Documentation Template

### `POST /api/v1/customers`

Create a new customer record.

**Auth:** Bearer token required

**Request Body:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| name | string | Yes | Customer full name (1-200 chars) |
| email | string | Yes | Valid email address |

**Response:** `201 Created`
```json
{
  "data": { "id": "cust_abc", "name": "Alice", "email": "[email protected]" }
}

Errors:

## 7. Documentation Maintenance

### Keep Docs Near Code

src/ auth/ login.py README.md ← Auth module docs live with auth code docs/ architecture.md ← System-level docs in docs/ runbooks/ ← Operational docs

### Freshness Rules

| Trigger | Action |
|---------|--------|
| API endpoint changed | Update API docs in same PR |
| New environment variable | Update README + .env.example |
| Architecture decision | Write or update ADR |
| Production incident | Update or create runbook |
| New developer onboarded | Test README, fix gaps found |

## 8. Review Checklist

When reviewing documentation:

- [ ] Answers "what does this do?" in the first paragraph
- [ ] Code examples are complete and runnable
- [ ] Commands are copy-pasteable
- [ ] No stale references to old code, endpoints, or config
- [ ] Diagrams are up to date
- [ ] Written for the target audience (not the author)
- [ ] No jargon without definition
- [ ] Links work and point to current resources

## 9. Anti-Patterns

| Anti-Pattern | Problem | Fix |
|---|---|---|
| Docs written once, never updated | Stale docs are worse than no docs | Update in same PR as code changes |
| Wall of text | Nobody reads it | Use headings, tables, code blocks, diagrams |
| Documenting obvious code | Noise, maintenance burden | Document "why", not "what" |
| Screenshots of terminal output | Can't copy-paste, hard to update | Use code blocks with text output |
| "See the code for details" | Reader has to reverse-engineer | Write the explanation |
| Assuming reader context | "Just run the usual setup" | Spell out every step |