“Big design up-front is dumb. No design up-front is even dumber.” David A. Thomas

Documentar ou não arquitetura de software é assunto controverso e polêmico. Percebemos que muitas empresas optam por não documentar arquitetura dos sistemas, os quais desenvolvem e mantêm. Essa decisão talvez seja, por “traumas” de processos pesados do passado, arquitetos de torre de marfim ou até mesmo pela interpretação equivocada do manifesto ágil.

Agora, negar a utilidade da documentação arquitetural pode ser muito arriscado para o processo de engenharia de software a longo prazo. Uma boa documentação arquitetural, deve produzir alinhamento de propósito do time que, eventualmente, habilita autonomia de atuação. Resultando em decisões mais assertivas do time e consequentemente em um ganho de produtividade. Afinal de contas, uma boa documentação arquitetural deve remover ruídos na comunicação e aumentar as chances do time implementar a arquitetura planejada do jeito certo.

Acreditamos que a pergunta a ser feita não deveria ser documentar ou não, mas sim, qual o custo correto da documentação arquitetural. Isto porque, uma vez convencidos de que a documentação arquitetural tem utilidade, o problema é acertar a medida certa. E neste ponto, temos visto muitos times desistindo de documentar arquitetura, uma vez que acabam documentando “tudo”. Lembrem-se, documentação é uma ferramenta de comunicação e não necessariamente quanto mais ampla a documentação, melhor será a comunicação! Na verdade, neste caso teremos apenas documentação arquitetural custando muito caro e entregando pouco valor ao negócio.

Então, quanto deveria custar a documentação? A resposta mais simples é: “Código + Documentação deve custar menos do que apenas código”. Isto é, a documentação arquitetural deve ser dois pilares, alinhamento de propósito e o porquê das decisões. Estes dois pilares, feitos da maneira correta, mitigam a erosão arquitetural, evitando ao máximo decisões de arquitetura que adicionam complexidade adicional ao software. Considerando que complexidade é custo, então boa documentação arquitetural é um esforço para manter o software funcionando ao longo do tempo, com a menor complexidade acidental possível.

E como podemos fazer documentação arquitetural na medida certa? Na EximiaCo, encorajamos os times a manterem duas práticas arquiteturais: Architecture Haiku e Architecture Decision Records (ADRs).

A primeira prática é uma ideia proposta por George Fairbanks, que consiste em um documento super simples (deveria ser no máximo uma folha A4), que descreve as principais características da arquitetura do software em questão. Neste documento, devemos inserir dados que forneçam alinhamento de propósito para o time, como por exemplo: objetivos de negócio, restrições, atributos de qualidade, integrações com outros sistemas e principais estilos arquitetônicos adotados. Percebam que com um bom Haiku, os processos de onboarding tendem a ser mais fáceis, além de fornecer um ótimo ponto para alinhar expectativas com o time de negócio.

A segunda prática, são as ADRs que falam sobre as decisões arquiteturais tomadas em um software. Michael Nygard, fala que uma das coisas mais difíceis no ciclo de vida de um software é rastrear a motivação por trás das decisões. Inclusive, Nygard vai mais longe, dizendo que uma pessoa do time pode ficar perplexa, furiosa ou encantada com uma decisão tomada, mas sem entender o porquê da decisão, essa pessoa apenas poderá aceitar cegamente a decisão ou alterá-la cegamente. Por isso, ADRs devem ser documentos que falam muito mais sobre o porquê de uma decisão arquitetural, do que a decisão propriamente. Inclusive, recomendamos que dentro das ADRs esteja explícito os trade-offs dessa decisão, pois ao fazer isso, provocamos o time a refletir nos prós e contras.

Estas duas simples práticas e seus benefícios, na nossa opinião, justificam e muito a decisão de documentar arquitetura de software. Mas é importante ressaltar que mesmo essas práticas implementadas de forma equivocada acabam gerando mais custo do que ganho. Afinal, uma documentação “ruim” não vale nem os bytes utilizados para armazená-la.

Então, gostaram do assunto? Temos um capítulo inteiro do Manual do Arquiteto falando sobre documentação e recentemente gravamos um Eximia Talk sobre o assunto.