O “mito” da documentação

Ultimamente tenho lido muito respeito de desenvolvimento ágil, principalmente no que diz respeito a Scrum. Navegando por aí, caí no blog de James Shore, co-autor do livro “The Art of Agile Development“, da editora O’Reilly. Vasculhando o blog, vi um artigo chamado “The Documentation Myth”, que pode ser lido
na íntegra (e em inglês) clicando neste link. Vale ressaltar que, assim como grande parte das pessoas que postaram comentários no referido blog, eu concordo/discordo de partes do texto, e cabe a cada um fazer sua avaliação pessoal. Mas achei bastante interessante e aqui sintetizo, em português, a idéia do mesmo:

O mito da documentação

Um dos grandes mitos do desenvolvimento ágil é que equipes ágeis não documentam seu trabalho. Realmente, equipes ágeis preferem conversas cara-a-cara do que comunicação através de documentos, e preferem escrever documentação para manutenção, no final do projeto, do que no começo (significando menos retrabalho e garantido conteúdo atualizado).

Junto com as acusações de más práticas de documentação, há um outro mito: “Documentação é uma coisa boa”.

Pessoas pensam “estou tendo problemas para entender isto!” e, depois de quebrar a cabeça, amaldiçoam o desenvolvedor pela sua falta de visão de documentação.

Muitos programadores escrevem linhas e mais linhas de comentários, antes de realmente começar a implementar. Mas isso não significa que a implementação que vem a seguir é de qualidade! O bom, desta forma, não vem automaticamente (e necessariamente) da prévia documentação. Isto é um mito!

Então o que é realmente bom? O que é que estamos procurando quando vamos atrás da documentação? A resposta é: Respostas.

Se você mudar sua forma de pensar, procurando as respostas, e não apenas documentação em si, você irá mudar inteiramente sua perspectiva. Documentação então é um meio para um fim, e não um fim em si própria.

A realidade é: queremos respostas, elas sim nos ajudam. E o quanto mais rápido as temos, melhor é.

O melhor caso é quando, as vezes o próprio código fonte, bem escrito e com partes bem nomeadas, não precisa nem de comentários, é intuitivamente óbvio. XP prega isso, e realmente não é uma coisa fácil de atingir, mas é o que se deve tentar.

O segundo melhor caso é quando é possível perguntar a alguém e obter logo a resposta. É o caso de equipes ágeis, onde se recomenda ter equipes com seus membros distribuídos através de várias funções. Os ganhos de produtividade por causa da comunicação são incríveis.

Ainda, continua sendo bom ser possível ir ao Google e procurar pela respostas. Algumas vezes vou ao Google e digito minha mensagem de erro. Descubro que 500 pessoas tiveram o mesmo erro, e proveram soluções. Fantástico.

Por último da lista de como/onde obter resposta, está a atividade de ler documentação atrás da mesma. è claro que algumas vezes a documentação é divinamente organizada, maravilhosamente escrita, e prazerosa de ler. Sim. Mas muitas vezes não. E quanto mais documentação você tiver que ler para obter sua resposta, pior. Ter muita documentação não é bom. A única coisa boa sobre ter toneladas de documentação é o jeito como isso soa.

Então, da próxima vez que você ouvir alguém reclamando sobre a falta de comentários ou de documentação, pare-o por um momento. Do quê realmente ele está reclamando? O código não está claro? A biblioteca tem uma organização pobre? Talvez corrigir isso primeiro fosse a melhor solução. Ou, talvez, nada está errado, e esta pessoa está sucumbindo ao mito da documentação.