Documentar ou não documentar? Eis a questão!

Gabriel Kohlrausch
“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.

Compartilhe este insight:

Comentários

Participe deixando seu comentário sobre este artigo a seguir:

Subscribe
Notify of
guest
0 Comentários
Inline Feedbacks
View all comments

AUTOR

Gabriel Kohlrausch
Arquiteto de software com experiência executiva e especialista no desenvolvimento de aplicações corporativas complexas.

SOLUÇÕES EXIMIACO

Arquitetura de Software

Evolução e modernização de aplicações para suportar mudanças de escala.

NOVOS HORIZONTES PARA O SEU NEGÓCIO

Nosso time está preparado para superar junto com você grandes desafios tecnológicos.

Entre em contato e vamos juntos utilizar a tecnologia do jeito certo para gerar mais resultados.

Insights EximiaCo

Confira os conteúdos de negócios e tecnologia desenvolvidos pelos nossos consultores:

Engenharia de Software

Três vantagens reais de utilizar orquestradores BPM para serviços

Arquiteto de software e solução com larga experiência corporativa
Desenvolvimento de Software

Os principais desafios ao adotar testes

Especialista em Testes e Arquitetura de Software
Arquitetura de Dados

Insights de um DBA na análise de um plano de execução

Especialista em performance de Bancos de Dados de larga escala

Acesse nossos canais

Simplificamos, potencializamos e aceleramos resultados usando a tecnologia do jeito certo

EximiaCo 2022 – Todos os direitos reservados

0
Queremos saber a sua opinião, deixe seu comentáriox
()
x

Documentar ou não documentar? Eis a questão!

Para se candidatar nesta turma aberta, preencha o formulário a seguir:

Condição especial de pré-venda: R$ 14.000,00 - contratando a mentoria até até 31/01/2023 e R$ 15.000,00 - contratando a mentoria a partir de 01/02/2023, em até 12x com taxas.

Tenho interesse nessa capacitação

Para solicitar mais informações sobre essa capacitação para a sua empresa, preencha o formulário a seguir:

Tenho interesse em conversar

Se você está querendo gerar resultados através da tecnologia, preencha este formulário que um de nossos consultores entrará em contato com você:

O seu insight foi excluído com sucesso!

O seu insight foi excluído e não está mais disponível.

O seu insight foi salvo com sucesso!

Ele está na fila de espera, aguardando ser revisado para ter sua publicação programada.

Tenho interesse em conversar

Se você está querendo gerar resultados através da tecnologia, preencha este formulário que um de nossos consultores entrará em contato com você:

Tenho interesse nessa solução

Se você está procurando este tipo de solução para o seu negócio, preencha este formulário que um de nossos consultores entrará em contato com você:

Tenho interesse neste serviço

Se você está procurando este tipo de solução para o seu negócio, preencha este formulário que um de nossos consultores entrará em contato com você:

× Precisa de ajuda?