Acredito que em todos os projetos nos quais já trabalhei, documentação foi um fator determinante para o sucesso ou fracasso do projeto. Documentação é muito importante e chega a ser irresponsável dizer que documentação é inútil.
Na minha opnião, documentação é uma forma de comunicação entre você (programador/documentador do presente) e você ou outros (programadores/gerentes do futuro – sendo futuro qualquer momento posterior à escrita da documentação). Através da documentação, tem que ser explicado para o próximo o que aquele sistema ou módulo faz. Essa é a função primordial da documentação.
Mas documentação não é apenas escrever dezenas de UMLs. Como disse, documentação é uma forma de comunicação e por definição não pode estar restrita à modelos. Modelos são ótimos para termos um lugar de onde partir (afinal, a melhor forma de aprendizado é através da cópia), mas temos que ter consciência de que devemos criar nossas próprias formas de comunicação com nossa equipe futura.
O que muitos acreditam erroneamente é que agilistas não gostam de documentação. Isso com certeza não é verdade. A maioria dos agilistas que vejo é mais preocupada com documentação do que desenvolvedores que utilizam processos tradicionais. A grande diferença é como cada um lida com a documentação.
Em um processo tradicional, a documentação é vista como uma obrigação. E obrigações são chatas e entediantes, não importa qual seja. Os agilistas encaram de outra forma. A documentação é uma responsabilidade de toda a equipe.
Então você não pode ter alguém responsável por escrever a documentação em uma equipe? Claro que pode (e talvez deva). Mas o ponto de ser uma responsabilidade afeta todos os tipos de documentação, não apenas os que devem ser entregues a algum gerente/supervisor/chefe.
Uma documentação que costuma ser muito ignorada é o próprio código. Como documentação é uma forma de comunicação entre o agora e o futuro, o código fonte da aplicação é o primeiro ponto de contato. Código auto-documentado é um dos principais tipos de documentação. Nenhum outro é capaz de suprir sua falta, porque esse é o código que realmente roda em produção (e consequentemente é quem traz dinheiro para a empresa). E notem a ênfase em auto. Eu não estou falando em ferramentas como javadoc, ndoc, ou comentários. Estou falando sobre código que além de legível é compreensível. Existe uma grande diferença entre os dois. Na comunidade de desenvolvimento SmallTalk isso é levado muito a sério. As boas práticas dizem que se você sentir a necessidade de acrescentar um comentário, você deve alterar o código para que fique mais compreensível e o comentário seja desnecessário.
Um segundo ponto de contato muito importante são os testes automatizados. Testes nada mais são do que documentação funcional do seu código, que ainda tem uma vantagem sobre os outros tipos. Eles são capazes de dizer se o seu código está certo com relação à quando o teste foi escrito. Se um teste falha, significa que o código está errado ou que o teste perdeu o sentido (ou seja, você nunca corre o risco de ficar com essa documentação desatualizada).
Esses são dois tipos de documentação que tem manutenção automática. Você não precisa lembrar de alterar o documento DOC4129-X porque acrescentou um método à classe Funcionario. Acrescentando o método (e o teste), a documentação estará feita.
Mas isso é suficiente? Nem sempre. Trabalhei com vários projetos onde foi o suficiente. Vários outros, não chegou perto do mínimo necessário. Quando estou desenvolvendo uma API para uso público, eu costumo documentar (com uma ferramenta como javadoc) toda a parte pública dela (por mais que muitas vezes eu gaste mais tempo com a documentação do que escrevendo essa parte pública), porque preciso explicar tudo o que vai acontecer, sem que o usuário precise olhar a implementação. Se quero que o projeto ganhe visão, preciso de uma documentação para o usuário, ensinando-o a usar o sistema (essa costuma levar mais tempo ainda).
O mais importante é lembrar que qualquer tipo de documentação exige esforço. Quanto desse esforço é convertido em valor para o projeto? O Toyota Production System é completamente baseado em eliminação de desperdício. E desperdício é qualquer coisa que não acrescente valor ao produto ou cliente. Quanto da documentação nos seus projetos atuais agregam valor aos seus clientes? Todas as 10 páginas para se criar uma modificação em uma classe? Então essa documentação é ótima. Nenhum dos diagramas UML? Então essa documentação precisa ser reavaliada.
Documentação é tão vital quanto água. Sem documentação, um projeto pode morrer. Com documentação excessiva, também.
