A boa documentação arquitetural reduz os custos totais de um software reduzindo os esforços necessários para entender e justificar decisões do passado. Ela também fundamenta e acelera as decisões emergentes indicando quais constraints e condições permanecem relevantes. Assim, para cumprir seu propósito, a documentação arquitetural é, ao mesmo tempo, descritiva e prescritiva.

Bem feita, a documentação atende a diversos públicos com diferentes anseios e expectativas. Ela extrapola as fronteiras dos times técnicos, colaborando, por exemplo, para que o “negócio” identifique se a arquitetura atende a suas demandas, alinhando expectativas de qualidade e custo.

Para os times técnicos, a documentação arquitetural provê, por exemplo, evidências que facilitam a resolução dos trade-offs impostos por requisitos conflitantes, opções de design e de tecnologias. Ela também funciona como “memória” de como trade-offs foram resolvidos no passado. 

A documentação arquitetural deve impactar desde as atividades de desenvolvimento até a operação. Para testadores, por exemplo, ela indica os pontos críticos a testar indicando onde acontecem as “conexões” entre os diversos elementos. Já para o time de segurança, ela relaciona que aspectos relevantes ao tema que foram observados, bem como eventuais pontos de exploração e melhoria. Para os DBAs, a documentação indica onde dados são criados e consumidos. Para os desenvolvedores, ela delimita a autonomia para decisões de design e orienta a implementação.

De qualquer forma, é inegável, entretanto, que o principal beneficiado com a documentação arquitetural é o próprio arquiteto. Seja para lembrar seu posicionamento passado, seja para entender o trabalho de outro profissional.

Manter documentação arquitetural de qualidade implica em esforço de planejamento e disciplina de execução.