Documentação em projetos ágeis sempre foi um assunto muito polêmico. Há ainda muita gente que a considera um mal necessário. Talvez não seja muito difícil definir uma boa estratégia de documentação se houver um pouco de bom senso e criatividade. Como disse Scott Ambler, um projeto ágil persegue dois objetivos. (a) Objetivo primário: Entregar software funcionando (b) Objetivo secundário: Dar sustentabilidade para o próximo esforço.

Documentação tem haver com o objetivo secundário. O fato de ser secundário não o faz ser menos importante. O fato é que cada documento que uma equipe deve gerar tem um custo, e esse custo tem que ser muito bem dimensionado com relação ao benefício que ele causa.

Um dos principais problemas da documentação é ela não estar atualizada. Uma boa abordagem para incentivar sua atualização é mantê-la o mais integrada possível com os outros artefatos que o desenvolvedor ou a área de qualidade trabalham no seu dia-a-dia. Assim será fácil e prazeroso mantê-la atualizada. Um exemplo disso pode ser observado na figura 1 (É melhor clicar na imagem para vê-la melhor). Ela representa um documento executável.

 
Figura 1: Exemplo de um documento executável

Na verdade, trata-se de um documento para execução de testes web com o Selenium, mas ele tem algo mais dentro dele. Há comandos que não são interpretados pelo Selenium, mas por um outro tipo de parser que pode ser utilizado para transformar o documento em um outro artefato; fazendo-o servir para diferentes propósitos, como por exemplo, uma especificação funcional, um caso de uso ou até um manual de usuário. No exemplo da Figura 1, pode-se notar na coluna parâmetro I, que há comandos que serão executados para a criação automatizada de um manual ou de uma especificação (spec) ou de ambas (manual, spec). Diferentes outputs podem ser gerados dependendo de onde o documento será visualizado: pdfs, documentos words, ou ainda podem ser diretamente publicados em portais ou wikis. Veja, na Figura 2, qual seria o resultado desse documento publicado no mediawiki.

 
Figura 2: Visão do documento executável já
transformado em uma página wiki

Repare também que o documento pode ser diretamente mapeado com o sistema de issue tracking. No caso desse exemplo, por meio de uma integração do Mantis com o MediaWiki. O documento pode comportar também links para outros issues relacionados, bem como outros documentos executáveis. Trata-se de uma forma bem interessante de manter os documentos vivos, fazendo parte efetiva do processo de desenvolvimento.