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.
Fora de tópico Mostrar Código Esconder Código Mostrar EmoticonEsconder Emoticon