IGTI Blog

Como documentar a Arquitetura de Software em cenários ágeis

Uma reflexão sobre o processo de documentação arquitetural em cenários menos prescritivos e como garantir que a missão da documentação seja cumprida em um cenário ágil.

Quando conversamos sobre documentação arquitetural é muito comum surgirem uma série de dúvidas recorrentes:  seria uma documentação a mais, além das que eu já faço? Seria responsabilidade de um profissional específico? Quais informações deveriam estar nesse documento? Não vamos precisar replicar informações em mais de um documento? Além dessas e algumas outras perguntas, existe a mais comum e relevante questão: pode me passar um template (modelo) desse documento?

Sobre as primeiras questões, vou dar algumas sugestões, mas, basicamente, tudo depende do seu processo ou acordos do time. Não basta me dizer que seu processo é SCRUM, mesmo porque ele não é prescritivo em muitos aspectos. Se quiser criar uma documentação separada, com foco estritamente arquitetural, tenha a preocupação de evitar redundância de informação. É importante, também, definir o responsável pela criação e manutenção de cada documento. Não precisa ser uma pessoa específica, poderia ser um papel. Por exemplo, o responsável pela documentação poderia ser definido como o analista que efetuou a programação no código-fonte.

Sobre quais informações deveriam estar nesse documento, entramos na discussão do que é decisão arquitetural e o que não é. Na visão de alguns autores e profissionais, a arquitetura de software pode focar mais em requisitos não funcionais, enquanto outros consideram que a documentação arquitetural poderia ser o repositório central de todas informações do projeto. Para definir como fazer no seu projeto, leve em consideração a importância de cada informação, o perfil dos profissionais disponíveis no seu time e a capacidade deles tanto para criar, quanto para consumir a documentação. Até mesmo o gosto pessoal de cada um pode ser importante nessa tomada de decisão.

Voltando à pergunta que considerei principal, sobre a solicitação de um template, vou explicar minha posição. As empresas dificilmente conseguem fugir da responsabilidade de fornecer templates a seus profissionais. Elas precisam garantir um nível de entrega mínimo, mesmo que existam profissionais menos capacitados. Muitas vezes, esses profissionais preenchem os campos desses templates sem fazer a mínima ideia do que cada informação significa. Sem falar no famoso NA (não se aplica) que sempre acaba sendo utilizado quando não está muito claro o que precisa ser feito.

Assim, o que defendo é seu time ou processo, defina quais são as preocupações importantes, saídas esperadas e um sistema de revisão conjunta da documentação que é criada, independente de qual for. A ideia é que o próprio time ágil seja capaz de direcionar o profissional que está criando a documentação para que esta seja simples e eficaz, tendo os conteúdos importantes para um bom desenvolvimento, e somente estes conteúdos. A capacitação de todo o time também é essencial. O template pode camuflar uma falta de capacitação, mas não a esconde para sempre. O IGTI oferece  especializações e MBAs relacionados à arquitetura de software que podem te dar um grande embasamento conceitual para tomadas de decisão.

Em um próximo artigo posso dar mais detalhes sobre o processo de grooming técnico, e como ele pode ser o guia que precisamos para documentar bem nossa arquitetura. Teria interesse? Deixe seu comentário!

Professor autor: Thiago Cunha