Documentação Evolutiva e Alinhamento de Expectativa na Engenharia de Software Ágil

TL;DR

• Questione o product owner, desenhe e planeje seu desenvolvimento: o óbvio deve ser questionado e dito.

• Participe e exija refinamento e planejamento; evite planejar "no quente", durante a execução.

• Colete e compreenda atributos qualitativos, e não permita que sejam vagos.

• Produza artefatos para serem utilizados como documentação incremental.

• Garanta que as respostas corretas foram adquiridas fazendo um check-list, e faça-o fazer parte do Definition of Ready.

Introdução

Vou partir do pressuposto que você já trabalha com uma metodologia ágil e, de alguma forma, refina e planeja seu backlog junto ao time.

Seu produto possui uma documentação evolutiva? Possui um alinhamento de expectativa com relação a requisitos não-funcionais, como performance, segurança e escalabilidade?

Atributos Qualitativos

Precisamos e esquecemos da importância do dos ritos de refinamentos (grooming/refinement) e planejamento (planning/replenishing). Este é o momento que o product owner deve ser questionado com relação a atributos qualitativos. Agora nossa fantástica lista das qualidades terminadas em "ility" serão muito utilizadas.

Todavia, este é um momento delicado e tende a conter termos abstratos. Não permita atributos qualitativos abstratos como "ser performático", "consumir pouca memória", utilize algo mensurável, seja data-driven, seja específico. Alguns exemplos são:

• Troque "Ser performático", por "Responder a consulta em até 50ms em uma carga de 100 requests/segundo";

• Ao invés de "Consumir pouca memória", utilize "Em uma carga de 10 requests/segundo consumir até 200MB";

• Evite "Dado cadastral deve ser seguro", ao invés utilize "dado cadastrado deve estar criptografado com determinado algoritmo" ou "dado apenas pode ser visível ao perfil Administrador";

• Ao invés de "Deve permitir anexos grandes", utilize "deve permitir anexos de até 100MB";

• Troque "permitir vários usuários simultâneos" por "permitir até 50 usuários simultâneos";

É uma arte definir atributos qualitativos, afinal para cada há um ou mais trade-offs conhecidos. Se é atribuída uma alta escalabilidade e disponibilidade em um determinado recurso, há um custo inerente, tanto operacional quanto infraestrutural. A própria teorema de Brewer é um exemplo:

"É impossível que armazenamento de dados distribuído forneça simultaneamente mais de duas das três garantias seguintes: consistência, disponibilidade e partição tolerante a falhas"

Artefatos

Há um passo importantíssimo que deve ser dado, tanto nas reuniões de refinamentos, quanto nos planejamentos, que é a produção de artefatos. Afinal, em um momento próximo este artefato pode - e deve! - ser utilizado como documentação incremental.

Os artefatos podem ser desde diagramas (DER, classe, sequência, fluxograma, C4Model), até wireframes e mock-ups. Não importa se criados em uma ferramenta fancy ou se rabiscado num papel de pão, lousa ou quadro digital. O importante é ter algo para ser utilizado como guia, principalmente quando tomada de decisão é envolvida.

Há diversas ferramentas disponíveis no mercado como Draw.io (permite colaboração realtime) ou Mermaid.js. Particularmente, prefiro utilizar Mermaid por gerar um código markdown-alike, e é integrado facilmente à documentação. Por exemplo, Git Lab e Azure Repos permitem utilização de Mermaid na Wiki, Issue e arquivos markdown (embora ainda possuam suas limitações).

Conclusão

Siga os ritos, tenha cadência, defina e deixe claro o Definition of Ready, para que o seu time tenha insumos suficientes para fazer um trabalho de qualidade em sua iteração de desenvolvimento. Garanta que as respostas corretas foram adquiridas fazendo um check-list.

Se apegue aos papéis! O papel do product owner é definir o que; o papel do desenvolvedor é definir o como. Artefatos arquiteturais definem muito bem o como; atributos qualitativos deixam claro restrições e qualidade inerentes ao produto.

Afinal, quando viajamos nos planejamos desde onde se hospedar, comer, quanto preciso levar em espécie, por quanto tempo e qual rota. Por que quando construímos software as vezes nos descuidamos e já "colocamos o pé na estrada"?

Como saber se você está pronto para a viagem rumo ao desconhecido se ainda nem abriu o mapa?