Documentação de software: vale a pena?

Hoje vou levantar um assunto polêmico: documentação de software. É incontestável a importância da documentação em quase todo processo de desenvolvimento de software. Documentar software traz diversos benefícios para a equipe de desenvolvimento. Mas não vou perder tempo aqui citando esses benefícios. Não faltam textos sobre esse tema. O que falta é bom senso na hora de decidir se um artefato de documentação deve ou não ser produzido.

Afinal de contas, para que a documentação serve? Serve para três propósitos principais: reduzir os riscos no início do desenvolvimento, facilitar a manutenção e, se for o caso, viabilizar a subcontratação. Na sua organização, talvez a documentação de software sirva a outros propósitos. Mas vamos nos concentrar nesses três, por enquanto. Vamos analisar cada um deles com um pouco mais de detalhe.

Reduzir os riscos no início do desenvolvimento

Quanto mais informação tiver sobre um sistema, menor é o grau de incerteza do desenvolvimento. Por exemplo, um levantamento de requisitos bem feito e com um razoável nível de detalhe vai evitar "surpresas" no meio do desenvolvimento. Mas a produção de artefatos de documentação tem um custo alto se comparada com outras abordagens para reduzir a incerteza de uma demanda de software. Cabe a cada equipe avaliar o seu custo de produção de alguns tipos de artefatos e decidir por aqueles que apresentam um menor custo e um benefício similar. Por exemplo, talvez uma lista de casos de uso seja suficiente e, ao invés de detalhar os fluxos de cada um deles, se possa adotar uma abordagem envolvendo técnicas de prototipação.

Facilitar a manutenção

Outro propósito da documentação é fornecer subsídios à pessoa responsável pela manutenção de um artefato de software. Ter em mãos um modelo de dados ou qualquer outro diagrama facilita a execução de qualquer alteração. Contudo, perceba que muitos artefatos de documentação são pouco ou sequer consultados diante da necessidade de uma alteração. Mesmo aqueles que poderiam ser consultados às vezes estão desatualizados – o custo de atualização é muitas vezes alto. E pode ser até que a documentação exista, esteja atualizada e seja útil para a manutenção. Mas neste último caso, a rastreabilidade dos artefatos de software pode não existir ou não ser confiável. O fato é: é alta a probabilidade de a sua documentação não servir simplesmente para NADA. Assim, vale a pena verificar com a sua equipe se a documentação está sendo atualizada e se ela é vista como útil pelos seus desenvolvedores.

Viabilizar a subcontratação

Subcontratação é um assunto delicado. Às vezes a empresa subcontratada estipula no contrato uma gama de artefatos de documentação que acabam por contribuir pouco para reduzir o grau de incerteza e aumentam o custo daquela que contrata. Às vezes é tão caro produzir a documentação exigida quanto desenvolver o software propriamente dito. Quer um conselho? Inclua no contrato um acordo de níveis de serviço e encontre uma forma de incluir a subcontratada desde o início do processo – de preferência já no levantamento de requisitos – e deixe que ela produza seus próprios artefatos.

Conclusão

É claro que falando assim tudo PARECE muito simples. Na prática você terá que ir substituindo seus artefatos de forma progressiva, sempre provendo o treinamento necessário para os membros da sua equipe. Sinceramente, acredito muito pouco em qualquer documentação. Na prática, as empresas acabam quase sempre dependendo das informações contidas na cabeça de cada pessoa. Mas não adianta ser tão radical – escrever sempre é bom para clarear as idéias. Pensando nisso, acho razoável considerar a produção dos seguintes artefatos de documentação:

- Lista de casos de uso.
- Modelo de dados.
- Protótipo de telas e/ou relatórios.
- Diagrama de componentes.
- Comentários de código (esse é o mais IMPORTANTE).