Convenções de Documentação

Documentation-as-code mantém o conhecimento da frota Python descoberto: ADRs explicam o porquê, runbooks explicam os passos das 3 da manhã, specs explicam o que é lançado, e READMEs direcionam novatos - tudo revisado em PRs como a lógica da aplicação.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

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

# README mínimo do Serviço
- Propósito
- Dev local (uv sync, pytest)
- Deploy / rollback (link para runbook)
- Proprietários (@team, CODEOWNERS)
- Dashboards + on-call

Quando usar isso:

• Bootstrap de novo serviço
• On-call não consegue encontrar o runbook
• ADRs no wiki divergem da realidade
• Auditoria solicita histórico de mudanças

Exemplo de Trabalho

# docs/adr/0002-celery-for-billing.md
 
## Status
Aceito
 
## Contexto
E-mails de faturamento e PDFs levam 5-120s; a API deve retornar 202 rapidamente.
 
## Decisão
Usar Celery com broker Redis; DLQ `billing_dlq`.
 
## Consequências
### Positivas
- Escala independente de workers
### Negativas
- Operar Redis HA; monitorar profundidade da fila
 
## Gatilho de revisão
Fila sustentada >50k ou necessidade de latência sub-segundo

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

O que isso demonstra:

• ADR usa seções padrão e gatilho de revisão
• Runbook tem comandos executáveis e chaves de flag
• README aponta para caminhos docs/ no repositório
• Todo o markdown revisado via PR

Mergulho Profundo

Como Funciona

• Fonte única de verdade - Branch principal do Git; wiki opcional.
• Templates - Templates de RFC, ADR, spec, post-mortem em docs/.
• Higiene de links - Links relativos dentro do repositório; verificação de links quebrados via CI opcional.
• Anotações de alerta - runbook_url aponta para markdown no branch padrão.
• Changelog - Release notes visíveis para o cliente geradas a partir de tags + links de spec.

Tipos de Documento

Notas de Python

## Ponteiro para docstring de módulo
"""billing_tasks.py - ver docs/runbooks/orders-api.md#celery"""

Armadilhas

• Runbooks apenas no Wiki - Divergência dos comandos de produção. Correção: Repositório canônico; wiki importa ou linka.
• ADRs nunca atualizados - Status enganoso. Correção: Substituir com novo número de ADR.
• Specs apenas em tickets - Perdidas quando o Jira arquiva. Correção: Cópia em docs/specs/ no PR.
• README desatualizado - Novos contratados bloqueados no primeiro dia. Correção: Mudança no README exigida em PRs relacionados a onboarding.
• Links relativos quebrados - A confiança se erode. Correção: Verificador de links opcional via CI em docs/.

Alternativas

FAQs

Relacionados

• Architecture Decision Records - Processo de ADR
• Contribution Guidelines - Docs de PR
• Incident Response Playbooks - Conteúdo de runbook
• Requirements to Technical Specs - Formato de spec
• Coding Standards & Style Guides - Docs de código

Versões de Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 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+, e uv 0.6+.