Porque é que a documentação está sempre desatualizada
A documentação de arquitetura costuma nascer bem: alguém dedica uma semana a escrevê-la e a desenhar os diagramas. Morre pouco depois, por uma razão simples: vive num sítio diferente do sistema. Cada alteração ao sistema obriga a lembrar-se de alterar também o documento, e ninguém se lembra.
O problema não é de disciplina. É de desenho: se manter a documentação for um trabalho à parte, não se fará.
Documentação como código
A alternativa é tratar a documentação como o código:
- Vive no mesmo repositório que o sistema e é revista nas mesmas alterações.
- Tem uma fonte única: o texto num formato simples e os diagramas descritos como dados, não desenhados à mão.
- As saídas são geradas: documento, diagramas, página web e versão imprimível saem dessa fonte com um modelo comum. Nunca se editam à mão.
- Um padrão visual partilhado: as mesmas cores, ícones e estrutura em todos os documentos da organização, para que se leiam da mesma forma.
O que incluir e o que não
Uma documentação de arquitetura útil é curta e estável:
- Visão geral e zonas.
- Componentes e para que serve cada um.
- Fluxos principais, numerados.
- Requisitos de qualidade acordados.
- Registos de decisão.
- Como se implementa e como se recupera.
O que muda todas as semanas (versões exatas, endereços, contagens) não se escreve à mão: obtém-se do próprio sistema ou liga-se.
A prova de que funciona
Uma documentação de arquitetura está viva se alguém que chega de novo conseguir perceber o sistema numa tarde e se uma alteração de arquitetura não for dada como concluída enquanto a documentação não a refletir. A segunda só é possível se atualizá-la for tão fácil como mudar uma linha no mesmo repositório.
Como o aplicamos: Arquitetura Cloud.