Quando o Manifesto Ágil declarou o princípio de “software funcional sobre documentação abrangente” em 2001, as equipes de desenvolvimento gostaram da ideia de uma nova maneira de trabalhar.

Documentação detalhada era o padrão, mas também era um empecilho à produtividade. Levava tempo para ser desenvolvida, deixava pouco espaço para a personalização e exigia manutenção contínua. Essa declaração direta no Manifesto Ágil reconheceu essas dificuldades, e muitas equipes a interpretaram como permissão para abandonar permanentemente a documentação.

Entretanto, as equipes que deixaram de produzir documentação enfrentaram um nova série de desafios: tiveram dificuldades para trocar informações, coordenar decisões e progressos, integrar novos membros da equipe ou solucionar problemas. Devido ao aumento do trabalho remoto nos últimos anos, esses desafios se tornaram mais intensos.

É óbvio que o desenvolvimento altamente orientado por documentação é ineficiente e ineficaz, mas a eliminação completa da documentação também é ineficaz. Isso levanta a questão: que papel a documentação desempenha no desenvolvimento Ágil?

Para descobrir, falamos com James Grenning, um dos autores originais do Manifesto Ágil e fundador da Wingman Software. Nesta entrevista, Grenning compartilha a intenção por trás dessa parte mal interpretada no Manifesto Ágil e discute como as equipes Ágeis dos tempos modernos podem encontrar o equilíbrio certo na documentação para trabalhar de forma eficiente.

Vamos falar da criação do Manifesto Ágil. O que motivou essa reunião? 

James Grenning: Eu estava trabalhando com o Bob Martin na época, e ele perguntou se eu queria participar do Lightweight Methods Summit no Snowbird Ski Resort em Utah. Os métodos Lightweight se referiam a abordagens como Programação Extrema, Desenvolvimento Orientado por Recursos e Scrum. Todos com muito menos cerimônias e artifícios do que as abordagens mais pesadas de processo popularizadas nos anos 80 e 90. 

Eu defendia a abordagem Extreme Programming (XP), mas também havia especialistas de todas as disciplinas de software Lightweight presentes na cúpula. Apesar de nossas formações diferentes, todos nós compartilhávamos o desejo de melhorar as metodologias de desenvolvimento de software. Nós brincamos que não queríamos ser conhecidos como os "lightweights" (que pode ser traduzido do inglês como "peso pena"), então outro objetivo era escolher um novo nome, que é o que chamamos de Ágil hoje.

Houve muito debate e pontos de vista opostos, com foco em encontrar áreas em que todos nós pudéssemos concordar. Sou engenheiro, por isso esperava falar sobre tecnologia, mas as pessoas e o trabalho em equipe surgiram como questões significativas. Transformamos esses temas em afirmações de valor, escolhendo um em detrimento do outro e enfatizando que os menos favoráveis ainda fossem valorizados. Foi assim que chegamos aos quatro princípios que você conhece hoje.

Eu não espera que alguém fosse se importar com o Manifesto Ágil quando Ward Cunningham o publicou pela primeira vez no site dele, mas muitas pessoas se importaram. Embora eu estivesse surpreso, acredito que isso revelou a quantidade de gente que se identificava com as dificuldades de desenvolvimento de software e desejava uma maneira melhor de trabalhar. 

Vamos nos aprofundar mais em uma das partes do Manifesto Ágil. Qual foi o objetivo inicial do "Software que funciona acima da documentação abrangente"? 

JG: Na época, o pensamento era: "Documentar primeiro, depois programar". No entanto, a documentação é cara. Não é apenas um benefício, mas também um custo.

Um dos objetivos da documentação tradicional era receber as solicitações do cliente por escrito e de acordo com o desenvolvimento antecipadamente, para que o desenvolvimento pudesse ser feito com calma O problema é que quando os clientes fazem solicitações de produtos apenas uma vez por ano, eles vão pedir tudo o que conseguirem imaginar, mas quando o software for entregue, eles já terão mudado de ideia.

Os entusiastas do XP, Kent Beck, Ward Cummingham, Ron Jefferies e outros estavam cientes de que esse método de criação de documentos não só consumia tempo, mas também impedia que a equipe incorporasse as lições aprendidas ou se adaptasse às mudanças. 

A frase "software que funciona acima da documentação abrangente" refletia uma grande mudança na forma como as pessoas viam a documentação. Ela recomendava que, em vez de priorizarmos a documentação extensiva antecipadamente, poderíamos gradualmente produzir documentação útil à medida que o software fosse sendo desenvolvido. 

Parece haver um estigma em torno da documentação Ágil hoje em dia. Você pode falar mais sobre sua opinião da função da documentação na metodologia Ágil? 

JG: As declarações do Manifesto Ágil tomaram a forma de "uma coisa é mais importante do que a outra". Mas, infelizmente, elas são frequentemente mal-interpretadas, como "uma coisa e não a outra". Observamos isso frequentemente com a documentação. 

Não queríamos insinuar que as equipes não deveriam produzir documentação alguma. Simplesmente não existe uma diretriz universal para documentação. Como não saberíamos o que dizer, o Manifesto Ágil não faz nenhuma menção sobre a melhor maneira de lidar com a documentação. As necessidades de cada equipe são únicas. Entretanto, só porque não há nenhuma orientação detalhada sobre como criar documentação, não significa que você não precise de nenhuma. 

A documentação pode ser extremamente útil para que as equipes e partes interessadas tenham um entendimento comum. A documentação de projeto, por exemplo, é necessária para manutenção do sistema, revisores externos e desenvolvedores remotos. A questão principal é reconhecer que os requisitos de documentação variam dependendo de fatores como tamanho da equipe, distribuição, regulamentação ou setor.

Eu aconselharia as equipes a usar o Manifesto Ágil como um ponto de partida para o debate, determinando quais as necessidades específicas que elas devem atender. Uma pequena equipe local, por exemplo, poderá ser capaz de compartilhar informações técnicas como arquitetura pessoalmente ou em um quadro branco virtual, enquanto uma grande equipe espalhada pelo mundo precisará encontrar novas maneiras de passar essas informações. 

Considerando que não há uma fórmula prescrita para documentação, que conselho você daria hoje às equipes Ágeis?

JG: Para começar, tenha em mente que todo documento que você criar deve ter valor. Antes de criar qualquer documentação no Ágil, considere para quem você a está criando e em que essas pessoas a usarão. Isso reduz o desperdício e poupa tempo ao envolver as pessoas adequadas na criação do documento. 

Quando decidir criar um documento, tenha em mente as seguintes sugestões:

Use imagens e gráficos para alcançar um alinhamento de alto nível. 

As imagens são uma excelente maneira de começar a explorar ideias e colocar todos em sintonia. Comece com uma visão geral do seu objetivo. Imagine que isso é um mapa. Ao criar algo do zero, comece com um documento que descreve o terreno, comunica convenções e auxilia você e sua equipe com a navegação pelo sistema. 

O que importa é que você saiba quando deve parar. Use estas imagens para investigar as interações do sistema e criar alinhamento, mas não exagere. Pode haver dezenas de cenários semelhantes; documente alguns para demonstrar o padrão e alinhar as partes interessadas.

Crie documentação de forma iterativa

Comece com uma visão do produto. Provavelmente será vaga e confusa; documente-a da maneira mais simples possível. Pode ser uma lista simples ou desenhos em um quadro branco físico ou virtual. Essa visão se torna mais clara à medida que os projetos avançam. Você aprende mais sobre o problema em questão e sua solução potencial.

Essa documentação deve ser geral, então tente mantê-la assim. Em seguida, você pode adicionar mais detalhes no próprio código. Um diagrama UML, por exemplo, mencionaria operações representativas, mas não assinaturas de funções detalhadas. Seu mapa do sistema ajuda você a navegar até os detalhes em vez de sobrecarregar sua visão com demasiados detalhes.

Você também pode usar o código de autodocumentação de forma iterativa: codifique com estrutura e sintaxe que explique claramente como o código funciona sem a necessidade de comentários ou documentação adicional. Por exemplo, em meu próprio website, notei casos em que o código que escrevi era difícil de entender. Parecia muito claro quando eu o criei, mas nem tanto duas semanas depois. Eu estava convencido de que alguém tinha invadido e bagunçado meu código! Então, eu mudei os nomes e a estrutura para melhorá-lo. Agora da próxima vez, o código fica mais fácil de eu entender. 

Aproveite o trabalho que você já está fazendo para criar a documentação.

Antes de criar qualquer documento, pergunte a si mesmo: existe uma forma mais natural de criar este documento que seja mais natural com o que já fazemos?

A documentação executável pode capturar detalhes sem adicionar trabalho extra. Deixe-me dar um exemplo. Eu costumava trabalhar para uma empresa que tinha uma etapa de processo definida: documentar como testar seu código por unidade. Era um processo manual que se tornou obsoleto com o tempo.

Tente testes unitários automatizados como uma alternativa a um processo manual documentado! Isso significa que, em vez de escrever um documento sobre como o código se comporta, você escreve testes para garantir que ele se comporte de uma determinada maneira. O teste falha quando o código deixa de seguir suas especificações. Com o desenvolvimento orientado por testes, você naturalmente mantém os testes e o código em sincronia — sem mencionar que repetir o teste é praticamente gratuito.

Os testes se tornam a documentação. Os testes lhe dizem como o código deve funcionar em termos claros, enquanto que se fosse escrito em uma língua natural, como o inglês, seria ambíguo e aberto à interpretação.  Um documento pode ficar desatualizado, mas os testes sempre refletem informações atualizadas, sem acrescentar trabalho extra. O documento mais barato é aquele que você nunca precisa escrever.