Documentação... importante até que ponto?

Ola Pessoal,

Hoje em dia o prazo de entrega de projetos tem sido um dois maiores problemas e muitas vezes a grande causa do fracasso de milhares de projetos, muitas pessoas associam esta demora a longa e extensa documentaçao que é produzida no projeto... porem outra grande parte dos problemas de um software, é justamente que ele nao atende as reais necessidades do cliente... isso acaba gerando uma duvida... até que ponto é necessario ter documentacao? qual a documentaçao que voces costumam usar nos seus projetos? quais diagramas?

Abraços Pessoal!

André Martins

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

This message was edited 1 time. Last update was at 28/09/2009 08:40:43

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?

1. Você tem um projeto que será desenvolvido por uma equipe externa;
2. 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).
3. Você tem um projeto que será usado em ambientes extremamente críticos ou onde uma falha pode ser fatal.
4. Você tem um projeto com requisitos extritos, que precisam ser seguidos, caso contrário algo catastrófico pode acontecer.
5. 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.

GUJ Expert Membro desde: 20/02/2008 12:32:59 Mensagens: 3371 Offline

O PMBok recomenda analisar risco e impacto pra decidir se vale a pena ou não o custo adicional.

Ola,

Muito obrigado pelas suas respostas pessoal, realmente eu acredito tambem que o preço de se manter uma documentacao atualizada é muito alto, estou com alguns projetos para desenvolver para uma empresa, e para curto periodo de entrega, dai surgiu a duvida a respeito da documentacao, por equanto, tenho pronto o ducumento de requisitos e diagrama de casos de uso, o que ja deu um trabalho para serem feitos de acordo com as necessidades do cliente e estarem coerentes... agora estava pensando na necessidade de um diagrama de classes... de atividades... mas acho que ja estaria criando muita pilha de documentacao... os sistemas sao bem grandinhos entao isso iria tomar tempo precioso. acham que da pra seguir um projeto media escala apenas com um documento de requisitos e casos de uso? eu pessoalmente numca tentei, sempre usei aquelas pilhas de documentacao, mas agora estou pensando em focar mais na agilidade, vou seguir firme assim mesmo, afinal de contas se nao tentar numca irei saber, hehe, até mais pessoal, e obrigado por suas respostas!

Abraços

André Martins

Olá

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:

Felagund wrote:Documentação é nessária ao meu ver para os desenvolvedores.

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

GUJ Expert Membro desde: 20/02/2008 12:32:59 Mensagens: 3371 Offline

Particularmente, gosto de ler os diagramas de classe quando estou trabalhando em um projeto, acho muito mais fácil do que ficar procurando diretamente no código.

Felizmente, nesse caso o Enterprise Architect facilita muito gerar informação e sincronizar com o código sem que seja necessário duplicar esforços.

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.

abraços

Notícias, artigos e o maior fórum brasileiro sobre Java