Jump to content

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


Postagens Recomendadas

  • Administradores
b82330ca238b93002900c69eddb0d267e55cd3e5

 

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

Link to comment
Compartilhe em outros sites

Crie uma conta ou entre para comentar 😀

Você precisa ser um membro para deixar um comentário.

Crie a sua conta

Participe da nossa comunidade, crie sua conta.
É bem rápido!

Criar minha conta agora

Entrar

Você já tem uma conta?
Faça o login agora.

Entrar agora


×
×
  • Create New...