# Documentation

> Create Runbooks for operational documentation. For ADRs, tech specs, requirements, LLD and technical analysis use the tech-writing skill instead.

- Skill: `nguyenthienthanh/documentation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nguyenthienthanh/documentation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nguyenthienthanh/documentation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: nguyenthienthanh (https://skillmd.com/u/nguyenthienthanh)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nguyenthienthanh/documentation

---


> **AI-consumed reference.** Optimized for Claude to read during execution.
> Human-readable explanation: see [docs/architecture/HIERARCHICAL_PLANNING.md](../../../docs/architecture/HIERARCHICAL_PLANNING.md)
> or [docs/getting-started/](../../../docs/getting-started/) depending on topic.


# Documentation (ADR & Runbook)

## When to Create

- **Runbook:** Service deployment, common ops tasks, incident response
- **ADR:** → use `skills/tech-writing` + `templates/decision-record.md`. That template carries the
  full 4-tier ladder (Y-statement → Nygard ADR → MADR → RFC) and picks the tier by decision size.
  The stripped ADR template below is kept only so existing links keep resolving.

## ADR Template

```markdown
# ADR-[N]: [TITLE]
**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-X
**Date:** YYYY-MM-DD

## Context — ## Decision — ## Options Considered — ## Consequences
```

Location: `docs/adr/ADR-NNN-description.md`. Keep immutable — supersede, don't edit.

## Runbook Template

```markdown
# Runbook: [Service]
**Owner:** [Team] | **On-Call:** [Contact]

## Prerequisites — ## Common Operations — ## Troubleshooting — ## Alerts & Escalation
```

Location: `docs/runbooks/service-name.md`. Test commands before documenting.

## Principles

- ADR: clear problem, options evaluated, consequences documented
- Runbook: commands copy-paste-ready, escalation path defined