Documentação de software: por que é importante e como fazer?

6,9K

A documentação de software é uma etapa indispensável para o uso e compreensão do produto.

Por melhor que esteja escrito o software, é a sua documentação que resolve possíveis dúvidas e gargalos posteriores.

São questões que, muitas vezes, aparecem durante o uso.

E o papel da documentação nesse contexto é claro: se está escrito, é lei.

Neste conteúdo, falamos sobre como fazer e explicamos a importância de documentar SaaS.

O que é documentação de software?

A documentação de software é uma etapa do desenvolvimento do produto que consiste em registrar em texto e de forma precisa o que há de essencial a saber sobre um sistema.

O documento de software é uma peça voltada a times de engenharia, de produto, de testes e demais usuários.

Existe para dar suporte aos times de desenvolvimento, além de ajudar o usuário a conhecer detalhes do software.

A ausência de uma documentação para o software está associada a problemas de usabilidade e legibilidade, entre outros.

Qual a importância da documentação de software?

Nós que trabalhamos com sistemas precisamos a todo momento consultar três fontes de verdades sobre um produto em uma empresa:

1. A documentação, que na maioria das vezes pode estar desatualizada
2. O código, que depende exclusivamente da disponibilidade das pessoas desenvolvedoras
3. E as pessoas, que estão há muito tempo na empresa.

A Engenharia de Software por muito tempo documenta, mas nem sempre consegue manter atualizada a principal fonte de consulta – a documentação do software -, e que deveria ser parte da estratégia do negócio.

Por necessidade de suporte e manutenção dos softwares, os times de engenharia deveriam ser capazes de decidir quais as características e necessidade precisa se documentar em cada feature, projeto e, assim, investir esforços pontuais para realizar esse processo.

Quando as pessoas de produto têm acesso à documentação técnica correta, elas podem tomar decisões de forma muito mais rápida.

Por exemplo, podem consultar instantaneamente os documentos criados junto com o software que explicam como funciona e registram o raciocínio por trás das decisões.

Não devemos tomar como prática normal pessoas desenvolvedoras  terem que executar buscas profundas no código, que se torna a única fonte de verdade.

Há uma necessidade de investimento importante no cenário de escassez de pessoas desenvolvedoras.

Isso porque, na maioria das vezes, quem executa essa tarefa de refinamento são pessoas desenvolvedoras  de nível mais sênior e conhecimento no negócio.

Quando o que se pretende documentar tem um alto custo de manutenção, talvez não tenha muito valor documentar.

Ou seja, quando a feature (ou funcionalidade) faz parte de um cenário que está em constante modificação, melhor não investir esforços.

Documentar uma nova funcionalidade retarda a equipe por uma semana ou duas. 

Não documentar essa feature retarda a equipe sempre que alguém novo precisar dessa informação, tanto na engenharia de software, quanto na compreensão ou suporte do negócio. 

O tempo investido na documentação nunca é desperdiçado. 

Como fazer documentação de software

Fazer a documentação de um software é, sobretudo, ajudar o público a entender o sistema e utilizá-lo adequadamente.

Então, é importante que o documento seja claro, preciso e sem recorrer a tecnicismos que prejudiquem esse objetivo.

Sempre lembrando que a documentação, muitas vezes, vai estar disponível em páginas online da empresa desenvolvedora, sendo acessada por qualquer pessoa.

Ainda neste conteúdo, vamos listar boas práticas para criar esse documento.

Antes, vamos pontuar o que entra na documentação do software.

Documente o que foi testado

Pode não ser recomendado documentar algumas partes de um sistema legado. 

Afinal, caso não tenhamos observado determinado uso, o ideal é que se façam os testes antes de seguir com a documentação. 

Existe a hipótese na qual um cliente que use nosso sistema há um bom tempo faça uso de um cenário que não temos imaginado – e isso não fica nada bem para a nossa imagem.

Muitas vezes, documentar é ter reuniões de alinhamento entre times diversos, de áreas diferentes. 

Com isso, você aumenta as chances para garantir que todos em sua organização estejam na mesma página em relação à visão de alto nível.

Isso não significa que todos precisam ter acesso aos pequenos detalhes técnicos do seu produto. 

Significa apenas que todos conhecem os pontos problemáticos que estão sendo resolvidos por engenharia de software e SRE (Site Reliability Engineering – Engenharia de Confiabilidade de Sites, em português).

Quando se trata de documentação que será utilizada por pessoas desenvolvedoras , o bom é que elas mesmas  mantenham alguma forma de atualização.

Apenas uma API em si não será suficiente para dar contexto para os casos de usos e vários possíveis contextos.

Recentemente, provocamos algumas equipes e conseguimos levantar casos de usos que não estavam documentados.

Eles estavam apenas na cabeça de algumas pessoas.

E através de um processo de colaboração, conseguimos essas respostas.

No entanto, muitas vezes, o que a pessoa tem como verdade já não mais coincide com o código em produção.

Documente ou não aconteceu!

Esta é uma frase que deveria ser uma OKR (Objectives and Key Results – Objetivos e Resultados-Chave, em português) de qualquer time de Engenharia de Software.  

Você já teve aquela sensação de que uma feature foi lançada e logo depois esquecida?

Para todo time que esteja construindo um produto de software, a documentação dele é mais do que um subproduto. 

Ela encurta a distância com usuários e aqueles que estão envolvidos no desenvolvimento do software.

8 dicas para uma boa documentação de software

Como prometido, vamos a alguns passos para criar uma boa documentação técnica:

1. Tenha conhecimento de qual será seu público-alvo e quando se usariam essa informação
2. Discuta sobre os temas que serão abordados – a equipe de desenvolvimento precisa participar ativamente desse processo
3. Encontre tempo para engajar pessoas e conseguir informação com outras pessoas interessadas em produzir documentos técnicos
4. Discuta o formato visual com o qual essa documentação será disponibilizada e organize em categorias e subcategorias
5. Comece um rascunho e direcione esse documento para quem será o usuário específico sobre o tema – definir isso junto dos PMs será a melhor forma de condução
6. Faça um documento que seja direto, breve, com frases curtas e sempre no modo imperativo. Por exemplo: “Entre com sua conta Google”
7. Procure avaliações com outros membros de sua equipe ou de outros times para que possam testar a documentação técnica quanto à usabilidade
8. Publique. Depois que sua documentação estiver no ar, convém executar mais testes sobre a sua eficácia, coletando comentários de usuários.

Gostou do conteúdo e quer entrar para a Vindi? Faça parte do nosso time de desenvolvimento!