Documentation Conventions

Documentation-as-code keeps Python fleet knowledge discoverable: ADRs explain why, runbooks explain 3am steps, specs explain what ships, and READMEs route newcomers - all reviewed in PRs like application logic.

Recipe

Quick-reference recipe card - copy-paste ready.

docs/
  adr/0001-use-fastapi.md
  rfc/TEMPLATE.md
  runbooks/orders-api.md
  specs/2026-pdf-export.md
README.md          # links to above

# Service README minimum
- Purpose
- Local dev (uv sync, pytest)
- Deploy / rollback (link runbook)
- Owners (@team, CODEOWNERS)
- Dashboards + on-call

When to reach for this:

• New service bootstrap
• On-call cannot find runbook
• ADRs in wiki diverge from reality
• Audit requests change history

Working Example

# docs/adr/0002-celery-for-billing.md
 
## Status
Accepted
 
## Context
Billing emails and PDFs take 5-120s; API must return 202 quickly.
 
## Decision
Use Celery with Redis broker; DLQ `billing_dlq`.
 
## Consequences
### Positive
- Independent worker scaling
### Negative
- Operate Redis HA; monitor queue depth
 
## Review trigger
Queue sustained >50k or need sub-second latency

# docs/runbooks/orders-api.md (excerpt)
 
## Rollback
kubectl rollout undo deployment/orders-api -n production
 
## Flag kill
CHECKOUT_MODE=checkout_v1
 
## Dashboards
- Grafana: Orders API SLO

What this demonstrates:

• ADR uses standard sections and review trigger
• Runbook has executable commands and flag keys
• README points to docs/ paths in repo
• All markdown reviewed via PR

Deep Dive

How It Works

• Single source of truth - Git main branch; wiki mirrors optional.
• Templates - RFC, ADR, spec, post-mortem templates in docs/.
• Link hygiene - Relative links within repo; CI check broken links optional.
• Alert annotations - runbook_url points to markdown in default branch.
• Changelog - Customer-visible release notes generated from tags + spec links.

Document Types

Python Notes

## Module docstring pointer
"""billing_tasks.py - see docs/runbooks/orders-api.md#celery"""

Gotchas

• Wiki-only runbooks - Drift from prod commands. Fix: Repo canonical; wiki imports or links.
• ADRs never updated - Misleading status. Fix: Supersede with new ADR number.
• Specs in tickets only - Lost when Jira archives. Fix: docs/specs/ copy in PR.
• README stale - New hires blocked day one. Fix: README change required in onboarding-related PRs.
• Broken relative links - Trust erodes. Fix: Optional CI link checker on docs/.

Alternatives

FAQs

Related

• Architecture Decision Records - ADR process
• Contribution Guidelines - PR docs
• Incident Response Playbooks - runbook content
• Requirements to Technical Specs - spec shape
• Coding Standards & Style Guides - code docs

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.