Desde que trabalho com desenvolvimento de software, venho observado a necessidade das empresas em gerar documentação. Esforços são feitos e muito tempo é investido na tentativa de criar e manter documentos de arquitetura (SAD – Software Architecture Document) em projetos de todos os tipos e tamanhos. E ao mesmo tempo, não é incomum que arquitetos de software, não saibam justificar por que a maioria das suas atividades diárias, acabam se resumindo na atualização de diagramas. E nem saibam dizer quem é o maior interessado em toda essa documentação.
Mas enfim, qual é a relação entre a documentação e o sucesso de um projeto ? Segundo Scott Ambler, nenhuma.

There is no solid relationship between project success and writing comprehensive documentation, and in fact it is more likely that the more documentation that you write the greater the chance of project failure.  Have you ever seen a project team write a comprehensive requirements document, get it signed off by your stakeholders, only to have the developers build something else?  Or the team actually builds to spec, only to have your stakeholders say that’s not really what they wanted?  Or the team delivers late or over budget, even though everything looked good most of the way through the project?  Have you ever seen a team create a comprehensive architecture model, have it reviewed and accepted by really smart people, only to see the architecture fail in practice anyway?  Or the developers simply ignore the model and then go off and build it the way that they want to?  Have you seen all this happen under the guise of management oversight, without management realizing what was happening until long after it occurred?
Scott W. Ambler

Na minha opnião, o que mais influenciou este comportamento, é um antigo conceito herdado da indústria de software e do waterfall model: o BRUF approach. Essa técnica é comprovadamente inviável e de fato não conheço nenhuma bibliografia séria, que recomende essa prática. A idéia de que seria possível levantar todos os requisitos de um sistema antes de gerar qualquer código executável, fez com que muitas empresas
ficassem por anos gerando documentos de todos os tipos e formatos.
Penso que documentar pontos fundamentais e use cases essenciais de um sistema não é um problema. O problema ocorre quando a documentação se torna o foco principal do projeto e as pessoas envolvidas tornam-se prisioneiras dos templates e da burocracia.
Muitos gerentes de TI, quando colocados em discussões como estas, refutam de formas diferentes, mas mas maioria se baseia no mesmo paradigma:

“Então vamos sair programando, sem nenhuma análise prévia ?!?!”

Não. A UML2 é uma ótima forma para investigar pontos críticos de um sistema, fazer avaliações de viabilidade de uma arquitetura ou comparar soluções para um determinado problema. E principalmente, a UML é uma fantástica linguagem de comunicação entre as equipes quando à utilizamos como UmlAsSktech. Alguns diagramas de iteração são muito úteis para expor idéias mais detalhadas numa reunião e para troca de informações entre arquitetos e programadores. Um diagrama mais simples, como de caso de uso, pode ser utilizado para demonstrar à stackholders e outros interessados no projeto, uma visão geral dos requisitos básicos de um sistema. Nestes casos, a abstração da UML é aceitável, já que preciso apenas de um overview sobre alguns pontos do meu sistema.

Na sua essência, a UML está relacionada com comunicação. E apesar de terem sido criadas várias ferramentas para geração de código fonte a partir de diagramas, acredito que a indústria de software ainda não conseguiu resultados satisfatórios com MDA e qualquer outra técnica de forward engineering. Ainda não vi nenhuma ferramenta que pudesse gerar código fonte aceitável em termos de qualidade a partir da UML. E acho que estamos bem longe disso por enquanto. Bons programadores, SEMPRE serão fundamentais.
Mas por que ? Porque a UML, apesar de ter evoluído muito desde a sua primeira versão, não está preparada para modelar TODOS os detalhes, comportamentos e funcionalidades que podem ser escritas no código fonte.

Além disso, outro ponto crítico sobre a supervalorização a UML, reside no simples fato de que ainda não  existe uma forma de validar UML. Como posso validar se um requisito está detalhado em um diagrama de sequência ? Como posso testar se uma regra de negócio do meu domínio foi corretamente “modelada” ?
UML não é executável e por isso não tenho como validar se um design é bom ou ruim. Todas as regras de negócio estarão implementadas no codigo fonte, e é código fonte, executável, que pode ser validado. É o código fonte executável, que poderei submeter a testes em TDD. Então por que não modelar em código ?

That, yes, but more. The source code is also the ONLY document in whatever collection you may have that is guaranteed to reflect reality exactly. As such, it is the only design document that is known to be true. The thoughts, dreams, and fantasies of the designer are only real insofar as they are in the code. The pictures in the reams of UML are only veridical insofar as they are in the code. The source code is the design in a way that no other document can claim. One other thought: maybe gloss isn’t in the writing, maybe it’s in the reading.
Ron Jeffries

Código fonte bem escrito é o melhor design e documentação que um programador pode fornecer, bem mais rico em detalhes do que qualquer diagrama UML. O problema é que a maioria dos desenvolvedores não encaram código fonte com uma forma de documentação e nem sequer levam em consideração que programação também é uma atividade de design. A preocupação com a clareza e simplicidade do código, a correta aplicação de patterns e a prática de refactoring também são atividades de design sob responsabilidade do programador. Estas práticas provavelmente produzirão a documentação mais atualizada e precisa do sistema. É claro, que muito código fonte que se encontra por aí, não é legível, e sequer pode ser encarado como documentação. Mas tenho certeza que isso esteja mais relacionado com a competência do programador, do que com o fato de que código fonte não possa servir de documentação. E de qualquer forma, digitadores de luxo nunca foram a melhor opção.

Vejo que na maioria dos casos, o simples é a melhor opção. Muitas vezes, papel, caneta e alguns rabiscos podem representar da melhor forma possível o comportamento de uma funcionalidade ou regra negocial. Geralmente uma boa conversa entre a equipe, pode economizar muitas horas de trabalho em ferramentas de modelagem e ganhar muito tempo de programação no projeto.
A UML é uma boa pedida, para promover comunição entre equipes, na validação de arquiteturas ou na verificação de algum ponto mais complexo do sistema. Mas o faça, quando a equipe sentir essa necessidade ou quando a complexidade do projeto exigir isso.
Modele em código fonte quando possível e cuide dele, faça do refactoring um hábito.
Não torne a geração de diagramas obrigatória para todos os projetos. Documente o necessário e corte as “gorduras”. Não burocratize demais. Não crie checklists demais. Não formalize em excesso.

E se ainda assim você optar em continuar documentando tudo. Pelo menos, economize papel e pense antes de imprimir. Porque afinal de contas, toda essa papelada vai servir pra que ?