doc-templates

doc-templates

Copy-paste fragments for recurring documentation structures. Each template is self-contained and opinionated. Pick the block you need; don't combine templates for the same page.

ADR (Architecture Decision Record)

# ADR-{NNN}: {Short imperative title}

**Date:** YYYY-MM-DD  
**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-{NNN}  
**Deciders:** @handle1, @handle2  

## Context

What is the situation that forces this decision? What constraints exist?
(1–3 paragraphs. No solution here — only problem framing.)

## Decision

We will {concrete action verb} {what}.

## Consequences

**Positive:**
- …

**Negative / trade-offs:**
- …

**Neutral:**
- …

## Alternatives Considered

| Option | Why rejected |
|--------|-------------|
| … | … |

Runbook Block

## Runbook: {System Name} — {Failure Mode}

**Severity:** SEV-1 | SEV-2 | SEV-3  
**Owner:** @team-name  
**Last tested:** YYYY-MM-DD  

### Symptoms
- Alert name: `{AlertName}` in Grafana / PagerDuty
- Observable user impact: …

### Immediate Triage (< 5 min)

1. Check service health: `curl -s https://api.acme.io/health | jq`
2. Check recent deploys: `gh run list --workflow deploy.yml --limit 5`
3. Tail logs: `kubectl logs -n production -l app=acme-api --tail=200`

### Remediation

#### Option A: Rollback last deploy
```bash
gh workflow run rollback.yml -f version=$(git describe --tags HEAD~1)

Option B: Scale up replicas

kubectl scale deployment acme-api -n production --replicas=6

Escalation

If not resolved in 30 min → page @on-call-lead via PagerDuty policy P_ACME_PROD.

Post-Incident

Open a post-mortem within 48 hours. Link: post-mortem template.

## Post-Mortem Skeleton

```markdown
# Post-Mortem: {Incident Title}

**Date:** YYYY-MM-DD  
**Duration:** HH:MM – HH:MM UTC ({N} hours)  
**Severity:** SEV-{N}  
**Author:** @handle  
**Reviewers:** @handle1, @handle2  

## Summary

One paragraph. What broke, for how long, who was affected, root cause in one sentence.

## Impact

| Metric | Value |
|--------|-------|
| Users affected | … |
| Requests failed | … |
| Revenue impact | … |
| SLA breach | Yes / No |

## Timeline (UTC)

| Time | Event |
|------|-------|
| HH:MM | Alert fired: `{AlertName}` |
| HH:MM | On-call paged |
| HH:MM | Root cause identified |
| HH:MM | Mitigation applied |
| HH:MM | Service fully restored |

## Root Cause

What was the technical root cause? (Not "human error" — trace to the system property that allowed the error.)

## Contributing Factors

- …

## What Went Well

- …

## Action Items

| Action | Owner | Due |
|--------|-------|-----|
| Add alert for X | @handle | YYYY-MM-DD |
| Improve runbook section Y | @handle | YYYY-MM-DD |
| Fix root cause: Z | @handle | YYYY-MM-DD |

## Lessons Learned

…