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.

O Globo, A Folha de São Paulo e a Associação Nacional dos Jornais são alguns dos críticos, detalhes nesta matéria do Jornal da Globo. Eis um dos trechos:

Para o jornal “O Globo”, as perguntas encaminhadas por escrito, são de propriedade do jornalista e do veículo e que por esse motivo a iniciativa da Petrobras desrespeita profissionais e atenta contra a liberdade de imprensa, ao violar o direito da sociedade de ser informada, sem limitações.

Será que realmente a sociedade seria informada sem limitações?

A resposta da Petrobrás para essa declaração do jornal foi que, se as perguntas são de propriedade do jornalista, as respostas são de propriedade da Petrobrás. O que é muito bem colocado.

Jornais agora não têm mais a chance de distorcer o que foi dito, pois a própria fonte da resposta publicou-a em seu site oficial. Sem falar que a imprensa “convencional” tem medo de perder espaço (audiência) para os blogueiros. Será que perde mesmo?

A internet, através dos blogs, mais uma vez mostra sua força. E a quem interessar, eis o endereço do blog da Petrobrás: http://petrobrasfatosedados.wordpress.com/

De minha parte, só posso dizer que achei de muita utilidade o serviço. Quanto mais informado, e quanto mais na fiel à fonte for a notícia, melhor. A Petrobrás é uma empresa muito importante para nosso país, e o que acontece com ela me interessa, e muito.

Era uma vez um jovem e forte lenhador que em um dia conseguiu derrubar 70 árvores, ao passo que o recorde era de 72.

No dia seguinte, querendo entrar para a história, acordou um pouco mais cedo, trabalhou duro, mas cortou apenas 68 árvores.

No dia imediato, acordou ainda mais cedo, esforçou-se ainda mais, almoçou correndo e cortou apenas 60 árvores.

Assim, desgostoso e desolado, sentou-se à beira do refeitório. Um velho lenhador, já sem vigor físico mas experiente, ficou com pena do jovem e, chegando ao seu lado, perguntou: “Meu filho, quanto tempo você separou para afiar o seu machado?”

Me sinto um pouco assim em relação à construção de software, uma vez que pessoas com quem convivo no ramo acham que o sucesso do desenvolvimento de um software é exclusivamente dependente do número de horas trabalhadas. Quantas vezes as ordens são para derrubar árvores e mais árvores, quando na verdade deveríamos parar um pouco para amolar o machado?