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

Tipo	Quando
README	Sempre por serviço
ADR	Decisão custosa de reverter
RFC	Design pré-implementação
Runbook	Execução on-call
Spec	Aceitação de funcionalidade

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

Alternativa	Usar Quando	Não Usar Quando
Backstage TechDocs	Grande catálogo	Frota pequena
Notion para specs de PM	Fluxo de trabalho de PM	Runbooks de engenharia
Apenas inline	Scripts <100 LOC	Serviços de produção
Confluence para auditoria	Mandato legal	On-call do dia a dia

FAQs

Markdown ou Sphinx?

Markdown é o padrão; Sphinx/MyST para bibliotecas de API públicas se publicar site de documentação.

Quem é dono dos runbooks?

Proprietário do serviço; plataforma revisa anualmente.

Numeração de ADR por repositório ou organização?

Sequencial por repositório; índice central linka entre repositórios.

Documentar OpenAPI?

FastAPI gera; snapshot do commit opcional para revisão de diff.

Documentos em espanhol?

Inglês canônico primeiro; pipeline translate-es pós-lançamento conforme política do site.

Comentários vs. docs?

Porquê em ADR; como em runbook; API em docstrings para módulos públicos.

Armazenamento de post-mortem?

docs/post-mortems/INC-123.md ou exportação da ferramenta de incidentes linkada do ADR.

Diagramas?

Mermaid em markdown preferido para diff de git.

Revisão de docs em PR?

Mesmos revisores para código+docs quando o comportamento muda.

O próprio cookbook do SME?

Seguir as mesmas convenções; diretrizes de contribuição se aplicam.

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

Convenções de Documentaçã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

Tipo	Quando
README	Sempre por serviço
ADR	Decisão custosa de reverter
RFC	Design pré-implementação
Runbook	Execução on-call
Spec	Aceitação de funcionalidade

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

Alternativa	Usar Quando	Não Usar Quando
Backstage TechDocs	Grande catálogo	Frota pequena
Notion para specs de PM	Fluxo de trabalho de PM	Runbooks de engenharia
Apenas inline	Scripts <100 LOC	Serviços de produção
Confluence para auditoria	Mandato legal	On-call do dia a dia

FAQs

Markdown ou Sphinx?

Markdown é o padrão; Sphinx/MyST para bibliotecas de API públicas se publicar site de documentação.

Quem é dono dos runbooks?

Proprietário do serviço; plataforma revisa anualmente.

Numeração de ADR por repositório ou organização?

Sequencial por repositório; índice central linka entre repositórios.

Documentar OpenAPI?

FastAPI gera; snapshot do commit opcional para revisão de diff.

Documentos em espanhol?

Inglês canônico primeiro; pipeline translate-es pós-lançamento conforme política do site.

Comentários vs. docs?

Porquê em ADR; como em runbook; API em docstrings para módulos públicos.

Armazenamento de post-mortem?

docs/post-mortems/INC-123.md ou exportação da ferramenta de incidentes linkada do ADR.

Diagramas?

Mermaid em markdown preferido para diff de git.

Revisão de docs em PR?

Mesmos revisores para código+docs quando o comportamento muda.

O próprio cookbook do SME?

Seguir as mesmas convenções; diretrizes de contribuição se aplicam.

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

Convenções de Documentação

Buscar na documentação

Convenções de Documentação