O papel da documentação no desenvolvimento de softwares

O que é uma documentação e como ela “desata os nós”do seu produto?

Quem trabalha na área de comunicação ou com a escrita sabe, de um modo geral, o papel que o conteúdo tem de ensinar, orientar ou engajar o leitor.

Trazendo essa mesma lógica para realidade de tecnologia, o technical writer tem um papel fundamental em conectar os desenvolvedores e demais profissionais envolvidos na criação de um software com seus potenciais consumidores.

(Se você não leu o primeiro artigo que fala sobre o que é redação técnica e o que aprendi nesses meses, sugiro dar um pulo lá antes de continuar esta leitura, ok?)

E como o tech writer faz isso? Por meio do que chamamos de documentação.

Vamos por partes: o que é uma documentação?

A documentação, também chamada de documentação técnica, é — como o nome sugere — um documento que traz as principais informações de um software para que você possa usá-lo.

Digamos que, a grosso modo, é como se fosse um bom e conhecido “manual de instruções”. Mas é importante ficar claro que ela vai além disso, tá?

Na prática, a doc ajuda você a realizar ações como:

• Instalar o software na sua máquina ou dentro da organização onde você trabalha;
• Entender as funcionalidades do produto e como usá-las no seu dia a dia;
• Configurar algo, seja de uma dependência, API, framework ou comando de acordo com diferentes sistemas operacionais que você usa, por exemplo;
• Customizar algo de acordo com o que estiver trabalhando ou com suas necessidades;
• Adicionar itens ou recursos que você já vinha usando.

E por aí vai.

Há pouco tempo, vi este artigo da VTEX sobre documentação e um ponto que achei ótimo ele levantar é o de que a doc estabelece para o usuário uma credibilidade técnica do seu produto, já que ela pode ser vista como a fonte única ou principal de informação do software.

Como disse logo no começo, a documentação é um dos “elos” que firmamos com nosso usuário. Se nos preocupamos em escrevê-la de maneira objetiva, didática e técnica, nós mostramos para você, que baixou ou comprou aquele software, como nos preocupamos em te oferecer uma melhor experiência de uso para que você resolva seus problemas e, quem sabe, nos indique para outras pessoas.

E aí, faz ou não faz sentido investir mais na documentação do seu produto?

Como se escreve uma documentação?

Essa pergunta, assim como praticamente tudo no universo da escrita, deve ser respondida com: depende.

Sim, pois de fato tudo irá depender do contexto em que você está. Ou seja, qual time no qual você atua, que tipo de produto você está desenvolvendo, quais são os tipos de informações técnicas que você precisa apresentar nesta documentação, entre outros.

Essas informações podem ser trabalhadas de diferentes formatos:

• Exemplos de código
• Vídeos
• FAQ
• Tutoriais
• APIs

Vou contar como foi o meu processo de escrita para facilitar a explicação.

Eu já contei para você que trabalho remoto com os times de produto. Por isso, mais do que nunca, foi fundamental trazer os desenvolvedores para perto do meu dia a dia, mostrando a eles a importância de contarmos sobre o funcionamento do produto com suas próprias palavras. Assim, poderíamos gerar maior identificação dos leitores com a documentação.

Afinal de contas, estávamos falando de soluções open source de dev para dev. Quem poderia falar melhor desse universo que não eles mesmos?

A partir daí, fomos, aos poucos, escrevendo sobre cada feature dos softwares. Às vezes, eu escrevia e eles revisavam ou vice-versa, sempre garantindo que o texto mantivesse um padrão para termos consistência ;)

Dessa minha experiência, os aprendizados que tive sobre este processo foram:

• Defina os objetivos com a documentação — quais informações precisam estar lá e quais podem, por exemplo, aparecer no repositório do projeto;
• Valide todas as hipóteses com o time do produto, desde a arquitetura do menu ao conteúdo propriamente escrito;
• Teste sua documentação com usuários — no nosso caso, testamos dentro de casa, mas já estamos evoluindo esses testes para público externo.
• Mantenha a doc sempre atualizada — já disse no último texto e repito aqui: documentação é um arquivo vivo, sempre estará sujeito a mudanças.

Tipos de documentação

Para falar melhor dessa parte, vou citar diretamente o artigo Software Documentation Types and Best Practices, do Prototypr, porque eles foram bastante didáticos. A imagem acima, inclusive, traduzi do material deles. Aqui, vou procurar resumir o que eles falam lá.

Basicamente, quando falamos de documentação, existem dois tipos principais: documentação de processos e de produtos.

O primeiro deles, como é de se imaginar, vai focar na parte processual de desenvolvimento do software, ou seja, a doc vai reunir tudo que foi produzido e definido durante o desenvolvimento do produto: planilhas, reports, etc.

Já a doc de produto, que é a que nos interessa aqui, irá descrever as funcionalidades do software, como ele foi criado e como você pode usá-lo no seu dia a dia. A partir daí, é possível ir destrinchando a doc até você chegar ao usuário final que, de novo, é o nosso caso com o open source na Zup.

Exemplos de docs

Antes que pergunte: sim, eu tenho alguns exemplos de doc! Inclusive, vou deixar primeiro as documentações que desenvolvi junto com time da Zup para vocês conhecerem meu trabalho mais de perto :)

• Documentação do Charles, nossa ferramenta open source de continuous deployments.
• Documentação do Ritchie, nosso CLI open source.

Além deles, vou deixar aqui algumas docs de produtos bem conhecidos no mercado de tecnologia, mesmo entre quem não é desenvolvedor:

• Doc do Google Cloud.
• Doc do Android.
• Doc da Apple.

Curti o assunto e quero ler mais. Onde acho?

Eu separei aqui os links de alguns artigos que li a respeito, além dos conteúdos que linkei ao longo do texto. Como pode ver, todos estão em inglês porque, ainda, a maioria dos materiais de estudo são escritos neste idioma.

• Begginers Guide to Docs
• Why documentation matters and why you should include it in your code
• 5 real life examples of beautiful technical documentation
• How to document source code responsibly
• Software documentation types and best practices
• Documentation in software architecture

Acho que por hoje é isso, hein?

Não deixe de comentar o que achou deste texto e, se quiser que continue escrevendo sobre technical writing, me traga suas dúvidas para os próximos artigos :)