Documentar ou não documentar? Eis uma questão que sempre foi
e continua sendo fonte de acaloradas discussões no meio da comunidade de
desenvolvimento de software. Entre extremistas que defendem que tudo deve ser
documentado ou que documentação é perda de tempo, ainda há os que preferem seguir
o ditado “a virtude está no meio”, ou seja, ficam no meio termo. Mas, então,
onde está a solução para essa questão?

Antes de procurar qualquer resposta para essa capciosa
pergunta, creio que seja importante descobrir por que a documentação existe, ou
por que ela é necessária. Ao pesquisar diversas fontes, descobri que essa
resposta, por incrível que pareça, não é tão clara nem tampouco fácil de achar.
A maior parte das publicações parte do conceito de que uma boa documentação
está diretamente relacionada com softwares de alta qualidade. Então, segundo
esse raciocínio, se você produzir uma documentação detalhada, seu software consequentemente
terá boa qualidade, o que não é uma verdade absoluta. O que existe na realidade
é um pressuposto de que, se uma equipe teve o cuidado de documentar o sistema
com detalhamento, as chances de que o produto final seja bom são grandes.

Mas, então, por que mesmo documentar? A principal questão em
relação a isso está relacionada à própria natureza dos softwares, que têm
algumas características predominantes:

• É
  complexo;
• Pode
  ser desenvolvido por várias pessoas;
• Pode
  ser desenvolvido para atender determinadas necessidades, ou para
  automatizar determinados processos;
• Está
  em constante evolução, sempre recebendo modificações;
• Será
  utilizado por pessoas que não necessariamente o desenvolveram;
• Será
  utilizado por pessoas que não necessariamente são especialistas em
  tecnologia (aliás, na maioria das vezes, elas não o são).

Claro que existem outras características, ou softwares com
características peculiares, mas essas são as mais gerais. A partir delas,
percebemos que a documentação de software então existe principalmente para:

• Registrar
  quais são os problemas a serem resolvidos pelo sistema, ou quais os
  processos que ele executa;
• Registrar
  como o sistema foi desenvolvido, para que outros programadores possam
  entendê-lo e realizar modificações;
• Registrar
  como o processo de desenvolvimento ocorreu, para que os próximos projetos
  sejam melhores;
• Registrar
  como o sistema deve ser utilizado pelos seus usuários.

A partir das respostas acima, fica mais fácil descobrir por
que se faz documentação para software. Isso é feito porque os gestores querem
garantir duas coisas principais:

• O
  futuro do sistema: ou seja, que ele possa ser ampliado e mantido com
  segurança. Ou, nas palavras de Mike Punter no texto “Programming for
  Mantainance”, “mais cedo ou mais tarde alguém terá que entender os
  programas que você escreve”;
• O
  uso do sistema: ou seja, para que os usuários tenham suporte para a sua
  utilização. Mais uma vez citando Punter, no mesmo texto, “programas devem
  ser escritos tanto para pessoas quanto para computadores”.

Assim, percebe-se que há um motivo muito forte e justo para
realizar documentação. Porém, uma coisa deve ser analisada: para documentar, as
pessoas gastam tempo; e, como diz uma frase famosa, tempo é dinheiro. Não há
pesquisas consistentes atualmente que indiquem quanto do custo do software é
consumido em média por atividades de documentação, mas o bom senso e a
experiência indicam que, se os documentos exigidos forem em grande quantidade e
com alto detalhamento, eles absorverão uma boa parcela do orçamento do projeto.

Uma vez que já está claro o porquê da necessidade de registrar
o desenvolvimento de um software, não parece ser aceitável a idéia radical de
não realizar absolutamente nenhuma documentação. Assim, uma vez esclarecida
essa parte, logo aparece outra pergunta: o que documentar? É nesse ponto onde
eu acredito que esteja a maior parte dos problemas.

Muitos defendem padrões para a documentação de software,
porém devemos lembrar que cada projeto é único e, portanto, deve considerar um
conjunto específico de ferramentas de gestão, desenvolvimento e, também, de
registro de informações. Concordo que devam ser criadas convenções para
escrever documentos dentro de uma empresa, para que haja uma linguagem uniforme
e que todos entendam o que está sendo descrito. Porém, estabelecer padrões
fechados de tipos de documentos e formatos que devem ser seguidos à risca para
todo e qualquer projeto, como acontece em alguns lugares, já é um pouco
demais. Considerando a questão da singularidade de cada projeto, é importante
que durante o processo de definição de documentos sejam analisados critérios
ligados principalmente ao seu uso futuro e aos custos para a sua produção.

A partir disso, é fácil perceber que a documentação deve ser
a mais simples possível, atendendo aos “porquês” da sua existência (uso do
sistema e futuro). Nesse caso, “simples” quer dizer suficiente para a sua
finalidade, sem excessos. Dessa forma, a chance de a documentação ser
efetivamente utilizada será muito maior, reduzindo o risco relacionado à não
atualização dos documentos de acordo com as mudanças implantadas no sistema ao
longo do tempo, e ainda colaborando com o orçamento global do software.

Outro ponto diz respeito à abrangência da documentação.
Revendo as principais características de um software, vemos que poderá ser
utilizado tanto por pessoas com conhecimento em tecnologia quanto para pessoas
sem conhecimento nessa área. Portanto, o total de documentos deve cobrir todos
os perfis necessários e cada registro deve ter as informações com conteúdo e
formato adequados a cada público. Além disso, do ponto de vista técnico, nada
substituirá um código bem escrito e comentado.

Ainda sobre “o que” documentar, vale lembrar uma armadilha
na qual frequentemente os gestores de projetos de software caem: o registro formal
do andamento do projeto. Sem dúvida, é importante dar visibilidade a todas as
partes interessadas no projeto sobre o que está acontecendo durante o seu
desenvolvimento. Porém, de acordo com Kent Beck, criador do processo XP (“Extreme
Programming”) deve-se “jogar para ganhar”, ao invés de “jogar para não
perder”. Quando se “joga para ganhar”, o trabalho do gestor fica mais focado
sobre a comunicação; porém, se “joga para não perder”, o gestor fica
registrando formalmente tudo o que pode para se defender em caso de problemas
no projeto.

Quando os gestores caem nessa armadilha, além de gastarem
indevidamente recursos do projeto, eles criam toneladas de documentos que
provavelmente nunca serão utilizadas, a não ser em caso de problemas. Aliás,
agindo dessa forma, há maiores chances de acontecerem problemas, já que o gestor
estará gastando mais tempo escrevendo documentos do que se comunicando
efetivamente com a equipe e com as partes interessadas. Isso tudo sem mencionar o
fato de que a pessoa que deveria ser o principal líder já entra com uma postura
pessimista, tendo a certeza de que o projeto terá problemas, o que contaminará
todos os envolvidos, e por isso não é interessante para ninguém.

Uma vez definido o que será documentado, surge a seguinte
questão: como documentar? A resposta mais rápida e a primeira que vem à mente de
pessoas acostumadas com o processo de software seria algo como “documentos
formatados de acordo com os padrões definidos pela organização”, ou alguma
frase similar. Sem dúvida, alguma documentação em papel, com uma linguagem
comum a toda a empresa acaba sendo necessária para todos os projetos. Porém,
não nos esqueçamos de que existem outras formas de registrar informações que são tão
ou mais ricas quanto documentos formais. Sabendo disso, gestores e suas
respectivas equipes devem analisar e escolher quais são os formatos mais
adequados a cada projeto.

Hoje temos a possibilidade de registrar fatos importantes do
desenvolvimento do software em fotos, vídeos, áudios, apresentações, além de
documentos nos mais diversos formatos (textos, planilhas, páginas web, simulações
etc.). O mais importante nisso tudo é pensar em dois aspectos principais:

• A
  mensagem registrada é suficiente para que outras pessoas entendam o
  contexto da situação descrita?
• O
  formato escolhido é adequado ao público-alvo e permite que a informação
  seja facilmente acessada?

Ao adotar vários formatos para o registro de informações, a
documentação do software recebe naturalmente um enriquecimento de detalhes,
especialmente se forem utilizados recursos multimídia, que têm maior riqueza
que textos planos. Outra vantagem adicional é que, em muitas vezes, registrar
informações em formatos não tradicionais gera economia de tempo. Por exemplo,
ao tirar uma foto de um esquema importante desenhado em um quadro, ou fazendo
um vídeo explicando determinado processo, a equipe economizará o tempo que
seria necessário para passar o esquema a limpo em um documento formal. E também
é importante lembrar que a documentação deve estar disponível na forma mais
fácil e rápida possível, e, em tempos de internet, nada mais justo do que
utilizar ao máximo o melhor que a rede tem a oferecer.

Depois de dizer tudo isso, então onde estaria a verdade
sobre documentação de software? Na realidade, não há uma resposta única para
essa pergunta, bem como ela não pode ser respondida por uma única pessoa. A
única verdade para a documentação é que ela deve ser desenvolvida a partir de
critérios que usem o bom senso como regra, considerando que cada projeto
precisa de um conjunto específico de documentos. Também deve ser considerado o
fator custo, além de políticas e aspectos culturais da empresa. E o mais
importante: as decisões devem ser feitas de forma colaborativa, envolvendo os
gestores e as suas respectivas equipes.

Assim, além de boa documentação, os projetos terão boa
colaboração de todos, o que ajudará em muito no sucesso e na qualidade dos
softwares gerados.

Referências:

BECK, Kent. Programação Extrema (XP) explicada. Porto
Alegre: Bookman, 2004.

COCKBURN,
Alistair. Crystal Clear: A Human-Powered Methodology for Small Teams. Addison-Wesley
Professional, 2004.

PUNTER, Mike.
“Programming for Maintenance” in Techniques of Program and System
Maintenance. QED Information Sciences, 1988, pg. 116.

SEI –
Software Engineering Institute. Concept of Operations for the CMMI. Carnegie
Mellon University, 2001. Disponível em: <
http://www.sei.cmu.edu/cmmi/background/conops.html>. Acesso em: 02/03/2009.

SOMMERVILLE, I. Engenharia de Software. 6ª edição. Pearson.
2003.