---
name: Technical Documentation
description: Write docs you'd want to read at 2am.
---
# Technical Documentation

Document the decisions and the "why"; the code already shows the "what". A README that restates the function signatures adds nothing.

## What to write
- **Getting started** that a stranger can follow verbatim and get a working result in <15 minutes. Test it on someone who didn't write it.
- **Architecture overview** — the big picture and the boundaries, with a diagram. This is what lets a new contributor navigate.
- **Decisions (ADRs).** Why you chose X over Y, with the constraints and trade-offs. Without this, future maintainers "fix" things that were deliberate.
- **Operational runbook** — the five things that go wrong and the exact command to check each.

## Style
- Present tense, imperative where possible. "Run X" not "You should run X".
- Update docs in the same PR that changes the code. Stale docs are worse than none — they actively mislead.