📊 Cap 15: Documentação Arquitetural & ADRs
Engenharia de Software • Architecture Decision Records, arc42 & Docs-as-Code
🗺️ A Morte dos PDFs de 200 Páginas
flowchart LR
subgraph VELHO ["Abordagem Legada (Word / PDF Estático)"]
V1["PDF gigante escrito no início do projeto.\nFica desatualizado no mês seguinte e ninguém lê! 🚨"]
end
subgraph NOVO ["Documentação Viva (ADRs + arc42 em Markdown)"]
N1["Arquivos .md versionados no Git junto com o código.\nEvoluem a cada Pull Request! ⚡"]
end
VELHO -.-> |"Evolução Docs-as-Code"| NOVO
style VELHO fill:#ffebee,stroke:#d32f2f,stroke-width:2px
style NOVO fill:#e8f5e9,stroke:#4caf50,stroke-width:2px
🎯 Slide 1: O Que é uma ADR?
-
Um registro conciso em Markdown de uma decisão técnica relevante.
- Estrutura Básica:
- Título & Status (Proposto, Aceito, Substituído).
- Contexto: Qual era a dor/problema?
- Decisão: O que escolhemos fazer?
- Consequências: Trade-offs positivos e negativos!
🎯 Slide 2: Por Que Registrar Consequências Negativas?
-
Toda escolha arquitetural tem um preço (Não existe almoço grátis!).
- Registrar os pontos negativos:
- Demonstra maturidade de engenharia.
- Alerta o time sobre riscos futuros.
- Explica por que certas restrições existem quando novos membros entram no time!
🎯 Slide 3: O Padrão arc42
- O arc42 é uma estrutura pragmática de 12 seções para documentar sistemas completos:
- Foco nos requisitos de qualidade.
- Integra diagramas C4 e decisões ADR.
- Zero burocracia, 100% de clareza técnica!
🔗 Navegação do Capítulo 15
| 📖 Ler Conteúdo Completo | 🧠 Fazer Quiz | 💻 Ver Exemplos | 🧩 Exercícios |
Slide 1 de 1
Atalhos: ← → Navegar • Espaço Avançar • F Tela Cheia • Home Início • End Fim