Documentação é nessária ao meu ver para os desenvolvedores. Existem ferramentas melhores para o sistema.
O grande problema de não atender as necessidades, é que é feito (quando é feito) o levantamento de requisitos do software, e depois disso a unica iteração com o cliente é na entrega do software. Isso nunca vai atender as necessidades do cliente. O cliente precisa estar envolvido no projeto, por que o sistema é pra ele, ele quem define o que precisa. Mas um programador deve dar suas sugestões. Nem sempre o que o cliente quer é o melhor pra ele.
Eu considero a documentação importante, mas prefiro muito mais legibilidade de código, váriaveis e metodos onde o nome diz o que ele faz.
[]'s
ViniGodoy
Eu já fui um defensor mais ferrenho da documentação, e a prática me mostrou que são raríssimos os casos onde ela é realmente necessária.
Como o colega falou, é muito mais valioso um processo de desenvolvimento interativo, e uma equipe focada em produzir código de qualidade e sem gambiarras, do que um monte de documentação que muitas vezes diz o óbvio (veja o caso de várias páginas de documentação de BD, que falam muito pouco a mais do que o ER já diz).
Em que casos eu documentaria?
Você tem um projeto que será desenvolvido por uma equipe externa;
Você tem um projeto onde o custo de manutenção será muitíssimo alto (software instalado em clientes com pouco acesso a rede, ou um projeto de firmware, por exemplo).
Você tem um projeto que será usado em ambientes extremamente críticos ou onde uma falha pode ser fatal.
Você tem um projeto com requisitos extritos, que precisam ser seguidos, caso contrário algo catastrófico pode acontecer.
Você está escrevendo uma publicação, e vai usar diagramas e documentação para exemplificar coisas.
Não é o caso da maioria dos sistemas comerciais. Já trabalhei com projetos nos casos 1 e 2. E já usei UML e DER no caso 5.
É bom lembrar que o custo de se manter uma documentação atualizada é altíssimo. Ele só vai ser compensado caso realmente o benefício que ela venha a gerar compense esse custo. Também é legal concentrar-se em gerar a documentação extritamente necessária, da maneira mais sucinta possível. Documentação “pela documentação” gera um peso morto no projeto, torna a informação importante mais difícil de achar e custa igualmente caro para se manter.
Documentação só pode ser longa e extensa se faz parte do projeto, isto é, se o cliente encomendou a documentação. Já participei de um projeto cujo objetivo era documentar o que foi feito (não me perguntem se alguém leu). Projetos normais não precisam de toneladas de documentos que ninguém lê.
Basta o seguinte:
E mais alguns poucos ou documentos descrevendo o projeto de forma clara de modo que sirva para o entendimento de qualquer pessoa de outros departamentos (mkt por exemplo). O ideal é que esta descrição seja a menor possível. Já participei de um projeto que ninguém conseguia me explicar o que ele fazia sem gastar muito tempo porque faltava justamente um documento claro e objetivo.
[]s
Luca
Alexandre_Gazola
O ideal é que a maior parte da documentação dos desenvolvedores seja o próprio código (código bem escrito, com testes de unidade e integracao automatizados, BDD, DDD, etc., etc.).
O que acho que pode ser interessante é uma documentação básica que descreva em alto nível o contexto do negócio em que o sistema está inserido e a idéia geral da solução de sistema proposta.
Olhando por um outro aspecto: a confecção de uma especificação funcional (uma descrição de um cenário de caso de uso, por exemplo) de um requisito mais complexo muitas vezes é útil. Neste caso, o valor não é nem do documento, mas o ato de escrever em si pode abrir a possibilidade de um entendimento maior do problema em questão. Isso até está um pouco relacionado ao processo cognitivo envolvido quando se faz TDD.
