Documentação de Software

Guilherme Borges

  A documentação de software ou documentação do código fonte, é um texto escrito que acompanha o software e geralmente explica como utilizá-lo. O termo pode significar coisas diferentes para pessoas de várias funções . Os textos podem acompanhar uma função, uma classe, um simples trecho ou módulo, ou consistirem num conjunto de manuais gerais e técnicos, e além de diagramas explicando o funcionamento do programa como um todo ou cada parte dele.

  A documentação de software pode auxiliar usuários e programadores sobre as rotinas que estão contidas no software facilitando o uso e o desenvolvimento para futuras evoluções.

  Quando falamos da importância da boa documentação de software, em projetos desta natureza, a imagem acima é talvez a melhor ilustração. É uma imagem “batida”, mas é sempre bom revisitá-la.

  Em projetos de software, quando ha especificação antes da construção, é muito comum o nível da documentação não estar bom, e isso gerar efeitos muito ruins no projeto.

  Alguns profissionais entendem que documentação de software (especificação, análise e projeto) é algo apenas para “encher linguiça”, outros fazem com entusiasmo mas esbarram nas “travas culturais” da equipe ou do cliente.

  Mas fato é: se for fazer, tem que fazer bem feito. Do contrário, não gera nenhum benefício, apenas prejuízos (não há neutralidade neste contexto).

  E muitas das vezes é o cliente, interno ou externo, quem produz parte desta documentação. E em alguns casos, este cliente entrega um material que deixa a desejar, e depois quando o problema estoura passa a responsabilidade para quem “aceitou” tal documentação e construiu algo errado.

  Nem todo software precisa de documentação, porém uma documentação quando bem feita, sempre torna um software melhor.

  Para começarmos a falar sobre documentação, precisamos primeiramente entender que o processo de documentar software muda de empresa para empresa e de produto para produto, porém ele faz parte do processo de produção, então um software que carece de documentação não pode ser considerado como um produto finalizado.

  Neste sentido, o que precisa ser documentado?

  Aqui na TecnoSpeed, aprendemos com o tempo que uma boa documentação precisa, além de seguir um certo padrão, trazer valor ao usuário final, de forma que ele entenda melhor o problema que está tentando resolver e também consiga utilizar mais facilmente nossos produtos, agilizando seu trabalho e reduzindo seus custos. Desta forma, optamos por seguir alguns passos para documentarmos nossos produtos. São eles:

• Contextualizar o problema
• Contextualizar o produto
• Descrever os detalhes técnicos
• Contextualização do Problema

  Para contextualizarmos o problema, precisamos explicar o cenário no qual este problema está inserido e quais são as implicações deste cenário. Como trabalhamos com documentos fiscais, procuramos orientar nosso cliente quanto a detalhes do documento fiscal, legislação e datas de obrigatoriedades, por exemplo.

Contextualização do Produto:

  Para contextualizarmos o produto, precisamos considerar que este é o primeiro contato do cliente com ele, portanto é importante explicarmos o que é o produto, quais são as vantagens de utilizá-lo e os problemas que ele resolve. Procuramos guiar nosso cliente pelo processo de instalação e “primeiro uso”, através de uma demonstração ou de um roteiro de integração. Através da demonstração procuramos conseguir com que o cliente utilize nosso software para realizar uma operação completa, como emitir uma nota fiscal, por exemplo. Já o roteiro de integração procura orientar o cliente a utilizar nosso software da maneira como ele foi pensado para funcionar.  Neste momento da documentação, vídeos explicativos e screencasts são muito úteis para facilitar o entendimento.

Detalhes técnicos:

  Após o cliente estar familiarizado com o cenário e o produto, podemos partir para uma documentação mais técnica. É neste ponto que ferramentas como dicionários de dados e diagramas nos ajudam a explicar mais detalhadamente o comportamento do produto.

  Em um componente, por exemplo, precisamos documentar as classes e métodos disponíveis, os parâmetros, retornos e as exceções que podem ser geradas. No caso de um documento fiscal, é importante documentarmos também as rejeições que os WebServices retornam, para que nosso cliente saiba o que fazer caso receba uma rejeição no retorno de uma comunicação.

  Por fim, um valor que fica implícito em nossa documentação é que, por ela fazer parte de nosso portal, ela torna-se colaborativa. Nossos funcionários e nossa rede de usuários podem contribuir para criar uma documentação melhor, através de sua participação nos comentários. Isto torna a documentação um artefato vivo do produto, estando em constante evolução. Assim podemos atender em tempo real às necessidades de nossa rede.

Referências:
Ateomomento
TecnoSpeed
Wikipedia