Documentação Ágil: Há clareza?

"Software em funcionamento mais que documentação abrangente.", Manifesto Ágil, 2001.

Documentação Ágil não é exatamente o assunto mais fácil de se abordar na comunidade. Quanto de documentação devo criar? O que funciona? O que não funciona? Como partir de um processo tradicional para um processo ágil com relação aos documentos? Esta é uma área que carece de explicação na comunidade.

Um post recente no blog Zen Agile fez a seguinte pergunta "Quanta documentação é  necessária?". O escritor falou sobre sua experiência com as agências governamentais e os motivos por trás dos grandes documentos de processos:

Foi sugerido que, toda essa documentação é necessária "pois somos do governo". Pesquisando mais encontrei as verdadeiras razões para isso:

1. O negócio precisa de informações consistentes para aprovar os builds
2. Os desenvolvedores precisam saber o que o sistema foi projetado para fazer
3. Outros desenvolvedores precisam saber como o sistema foi construído para fazer melhorias
4. Outros desenvolvedores precisam saber como o sistema foi construído para fazer manutenções
5. O governo requer de informações suficientes em ordem para saber porque o dinheiro foi gasto e como foi gasto

Na minha experiência, no entanto, poucas pessoas entendem a documentação de requisitos de negócios. Eles tendem a ler o plano do projeto para ter certeza do estado atual e lógico e se é está indo conforme eles planejaram, eles também usam o mapa dos processos para ter uma melhor noção, pois gráficos tendem a ser mais intuitivos do que casos de uso. Mas no geral, conseguindo assinar e aprovar algo que eles não tenham visto é meio ... bem ... não é lógico.

O blog, então, vai para um relatório alternativo da documentação que consiste em:

1. Articular o contexto via personagens, cenários e diagramas de contexto,
2. descrever o requisitos com mapas de processos, e matrizes de rastreabilidade,
3. documentar a solução com modelo de dados, site maps, navegação, e desenho da UI,
4. validar a solução via protótipos, assinaturas acontecem aqui, de forma iterativa, e
5. documentar o build do sistema o qual inclui código, testes, e modelo físico de dados.

Este processo acima tem foi criado a partir da experiência. Mas será que temos alguma coisa parecida hoje na comunidade?

Será que nós temos um consenso quando se trata de documentação? É realmente difícil falar porque pouco é escrito sobre o assunto. Talvez o assunto seja tão simples para escrever sobre. Ou talvez seja tão complexo e nós realmente não temos uma boa idéia para recomendar.

E você leitor tem alguma boa idéia? Por que será que tão pouco é escrito sobre o assunto?