O que uma boa documentação de software deve conter?

[Karina Harumi]

 

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:

1. Contextualizar o problema
2. Contextualizar o produto
3. 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