os diagramas arquiteturais não são suficiente para documentar todo o sistema; enquanto diagramas mostram a estrutura (“o quê”), a documentação arquitetural registra a intencionalidade (“o porquê”).
riscos da falta de documentação
- falhas de comunicação entre equipes
- dificuldade na manutenção e evolução de sistemas (perda de conhecimento tácito)
- onboarding lento de novos membros
a documentação é essencial para capturar a evolução do software, os objetivos técnicos e as motivações por trás das escolhas. a escolha do tipo de documentação depende da complexidade do sistema e da cultura da equipe. as duas principais abordagens são design docs e ADRs.
design docs
são documentos relativamente informais escritos antes de escrever o código. o ato de escrever força o engenheiro a pensar com clareza na solução e nos trade-offs.
- objetivo: avaliar ideias, identificar alternativas, reduzir riscos e alinhar o time
- benefícios: facilita a colaboração e a solicitação de feedbacks (RFCs) antes de gastar tempo escrevendo código
- formato: não existe um modelo formal rígido; cada empresa adapta seus templates. é mais uma prática de documentação do que uma metodologia.
podem incluir informações como:
- contexto e problema
- objetivos, requisitos funcionais e não-funcionais
- desenho da solução de arquitetura proposta e comunicação entre sistemas
- alternativas consideradas
- trade-offs, riscos e impactos
- plano de implementação
exemplos reais:
- os JEPs (JDK Enhancement Proposals) funcionam como design docs: JEP 0: JEP Index
- biblioteca de templates usados por empresas: Design Docs Library
ADRs (architecture decision records)
são registros curtos e objetivos que documentam uma decisão arquitetural importante e seu contexto. servem como o “diário de bordo” da evolução do software, com um histórico de como a arquitetura evoluiu.
é criado após a tomada de decisão, e mostra os registros de decisões, com contexto e motivações. uma forma de manter os ADRs atualizados é versionar junto com o código fonte.
cenários de uso: mudança de padrão de projeto, escolha de frameworks, decisões que impactam integrações etc.
estrutura básica
- título curto e direto
- status (proposto, aceito, depreciado).
- o contexto que motivou a decisão
- a decisão tomada
- as consequências (positivas e negativas)
recursos:
- repositório de templates e exemplos de ADRs: GitHub - ADR Examples & Templates