O dilema da documentação no processo de desenvolvimento de software

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 ficam no meio termo. Mas então, onde estaria esta resposta?

Antes de tentar responder esta 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 não é clara, nem tampouco fácil de achar. A maior parte das publicações sugere fazer documentação detalhada e padronizada, justificando uma relação direta com a qualidade do produto final, mas há trabalhos significativos que questionam isso.

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 e que, na maioria das vezes, não são especialistas em tecnologia.

 

A partir dessas características, percebemos então que a documentação de software existe principalmente para:

·         Registrar quais são os processos que ele executa;

·         Registrar como o sistema foi desenvolvido, 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 se quer garantir duas coisas principais: o “futuro” do sistema, para que ele possa ser ampliado e mantido com segurança; e o “uso” do sistema, para que os usuários tenham suporte para a sua utilização.

Percebe-se, assim, que há excelentes motivos para realizar documentação de software e, portanto, não parece ser aceitável a idéia radical de não produzir nenhum documento. Uma vez esclarecida essa parte, logo aparece outra pergunta: o que documentar? É neste ponto onde eu vejo a maior parte dos problemas.

Para documentar, as pessoas gastam tempo; e, como diz uma frase famosa, tempo é dinheiro. Não há pesquisas consistentes que indiquem quanto do custo do software é consumido em média por atividades de documentação, mas o bom senso indica que, se os documentos exigidos forem em grande quantidade e com alto detalhamento, eles irão compor uma boa parte do orçamento do projeto.

Muitos defendem padrões gerais para a documentação de software, porém devemos lembrar que cada projeto é único. Concordo que devam ser criadas convenções para escrever documentos dentro de uma empresa, para que todos entendam o que está descrito. Porém, estabelecer padrões fechados que devem ser seguidos à risca para todo e qualquer projeto, como acontece em alguns lugares, já é um exagero. A documentação deve ser adequada a casa projeto, sendo também a mais “simples” possível e atendendo aos “porquês” da sua existência (“futuro” e “uso” do software). Nesse caso, “simples” quer dizer suficiente e precisa. Dessa forma, a chance da 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, e ainda colaborando com o orçamento global do projeto.

Outro ponto diz respeito à abrangência da documentação. 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.

Ainda sobre “o que” documentar, há uma armadilha onde freqüentemente os gestores de projetos de software caem: o exagero no registro formal do andamento do projeto. De acordo com Ken 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, gastando mais tempo para escrever documentos do que para se comunicar com a equipe a as partes interessadas. Se somarmos a isso tudo o fato de que o principal líder do projeto já entra com uma postura pessimista, há um risco considerável (e evitável) associado à forma de gestão.

Depois de definir o que será documentado, surge a questão sobre como documentar. A resposta mais rápida que vem à mente de pessoas acostumadas com o processo de software seria algo como “documentos formatados de acordo com os padrões da organização”. 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, hoje existem outras formas de registrar informações que são tão ou mais ricas quanto documentos formais.

Gestor e equipe devem considerar o registro de 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.). Nesse momento, o fundamental é pensar se o conteúdo registrado será suficiente para que outras pessoas entendam o contexto da situação descrita, e se o formato escolhido é adequado ao público-alvo, permitindo que a informação seja facilmente acessada.

A utilização de recursos multimídia enriquece o nível de detalhe da documentação, algo que seria muito difícil de obter utilizando apenas textos. Outra vantagem adicional é que, muitas vezes, registrar informações em formatos não tradicionais gera economia de tempo. Por exemplo, ao tirar uma foto de um esquema desenhado em um quadro, se economiza o tempo necessário para passar o esquema a limpo em um documento formal. Também é importante lembrar que a documentação deve estar disponível na forma mais fácil e rápida possível, sendo indicado utilizar tudo o que a web tem a oferecer.

Depois de dizer tudo isso, onde então estaria a verdade sobre documentação de software? Vemos que não há uma resposta universal para essa pergunta, mas pode-se afirmar que a documentação deve ser desenvolvida a partir de critérios que usem o bom senso como regra, considerando um conjunto específico de documentos para cada projeto. 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 sobre documentação de sistemas devem ser feitas de forma colaborativa, para atender às necessidades de gestores, equipes e partes interessadas.

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

Marcus Rocha é Gerente de TIC da Knowtec