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

Type	When
README	Always per service
ADR	Costly-to-reverse decision
RFC	Pre-implementation design
Runbook	On-call execution
Spec	Feature acceptance

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

Alternative	Use When	Don't Use When
Backstage TechDocs	Large catalog	Tiny fleet
Notion for PM specs	PM workflow	Engineering runbooks
Inline only	Scripts <100 LOC	Production services
Confluence audit	Legal mandate	Day-to-day on-call

FAQs

Markdown or Sphinx?

Markdown default; Sphinx/MyST for public API libs if publishing docs site.

Who owns runbooks?

Service owner; platform reviews yearly.

ADR numbering per repo or org?

Per repo sequential; central index links across repos.

Document OpenAPI?

FastAPI generates; commit snapshot optional for diff review.

Spanish docs?

English canonical first; translate-es pipeline post-launch per site policy.

Comments vs docs?

Why in ADR; how in runbook; API in docstrings for public modules.

Post-mortem storage?

docs/post-mortems/INC-123.md or incident tool export linked from ADR.

Diagrams?

Mermaid in markdown preferred for git diff.

Doc review in PR?

Same reviewers for code+docs when behavior changes.

SME cookbook itself?

Follow same conventions; contribution guidelines apply.

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+.

Documentation Conventions

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

Type	When
README	Always per service
ADR	Costly-to-reverse decision
RFC	Pre-implementation design
Runbook	On-call execution
Spec	Feature acceptance

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

Alternative	Use When	Don't Use When
Backstage TechDocs	Large catalog	Tiny fleet
Notion for PM specs	PM workflow	Engineering runbooks
Inline only	Scripts <100 LOC	Production services
Confluence audit	Legal mandate	Day-to-day on-call

FAQs

Markdown or Sphinx?

Markdown default; Sphinx/MyST for public API libs if publishing docs site.

Who owns runbooks?

Service owner; platform reviews yearly.

ADR numbering per repo or org?

Per repo sequential; central index links across repos.

Document OpenAPI?

FastAPI generates; commit snapshot optional for diff review.

Spanish docs?

English canonical first; translate-es pipeline post-launch per site policy.

Comments vs docs?

Why in ADR; how in runbook; API in docstrings for public modules.

Post-mortem storage?

docs/post-mortems/INC-123.md or incident tool export linked from ADR.

Diagrams?

Mermaid in markdown preferred for git diff.

Doc review in PR?

Same reviewers for code+docs when behavior changes.

SME cookbook itself?

Follow same conventions; contribution guidelines apply.

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+.

Documentation Conventions

Search Documentation

Documentation Conventions