Coisas que ningum te ensina a fazer mas que todo mundo espera que voc saiba: escrever documentao

Documentar ou no documentar o cdigo no exatamente um consenso na comunidade. Muita gente diz que um cdigo bem escrito a prpria documentao. O argumento contrrio diz que se voc capaz de escrever um cdigo legvel, ento voc capaz de document-lo. Ter uma documentao adequada do projeto (que diferente de comentrios soltos ao longo do cdigo) ajuda tanto no onboarding de novos devs ( mais fcil entender como o projeto funciona quando tudo j est documentado) quanto para refatorar cdigos que foram escritos j a algum tempo, evitando que ele se torne legado.

Documentation As Code

DaC uma forma de automatizar a escrita da documentao com as mesmas ferramentas do cdigo que est sendo escrito. Desta forma, a documentao vai sendo escrita junto do cdigo e ao mesmo tempo do cdigo, o que torna a documentao um organismo vivo e continuamente atualizado. Uma das formas de se criar e manter esta documentao justamente a colocando nos arquivos de cdigo na forma de um comentrio especiais (com marcaes prprias) que podem ser extrados por um framework especifico que gera a documentao de uma forma organizada (em HTML, PDF, Markdown e etc).

Framework

Eu pessoalmente recomendo o JSDoc para projetos frontend pela facilidade de us-lo j com o javascript. Outras linguagens possuem seus prprios frameworks de documentao, como por exemplo o PHPDoc, o Swagger do Java e o Sphinx, do Python.

A documentao geralmente escrita na forma de um comentrio no prprio cdigo com uma marcao e depois exportada automaticamente para um documento, que pode ser lido pelo time de desenvolvimento, de produto e at mesmo por usurios (em alguns casos).

O que documentar?

Uma forma simples descrever as partes principais e explicar a funcionalidade das partes menores (ou auxiliares). Fique atento ao paradigma que est sendo usado. Se voc usa orientao a objeto, a parte principal ser uma classe, e a parte auxiliar ser um mtodo. Em programao funcional, a parte principal e as auxiliares sero funes, ento descreva a main e explique a utilidade das funes utilizadas na main.

Outro ponto que a documentao deve falar do negcio, e no do cdigo. Um cdigo bom e limpo auto-explicvel. A funo da documentao explicar a regra de negcio por trs dele e no o cdigo em si.

Como escrever?

Eu pessoalmente acho que cada trecho de documentao deve caber em um tweet. A idia no escrever um artigo para cada parte, apenas ajudar a explicar o que acontece ali. No entanto, aqui interessante procurar os padres da comunidade da linguagem que voc usa. Em Python, o padro ser mais extenso e, em alguns casos, at embutir testes nas docstrings.
Tenha sempre em vista quem vai ler a documentao. Se na sua equipe as pessoas de produto e operaes tambm tero acesso ao documento, no to legal usar linguagem tcnica demais.

O que no documentar?

Algumas coisas devem ser explicadas a nvel de cdigo, e no deveriam ir para a documentao do produto por referenciarem apenas a utilizao de um cdigo que no auto explicvel (como por exemplo uma RegExp). Quaisquer comentrio que s faa sentido junto ao cdigo no deve ir para a documentao. Todos, de forma geral, so uma prtica ruim e no devem nunca ir para a documentao (ou produo).

Seguindo o mapa da mina

Caso seu time esteja adotando a escrita de documentao, veja esse texto como um mapa da mina, que vai auxiliar todos a chegar mais rpido nas especificaes do software. Escreva com ateno, mantenha o documento sempre atualizado e o mais importante: leia sempre, isso vai te ajudar bastante (especialmente em refatoraes).

Para escrever este texto eu tive a reviso do Joo Bueno e do Caio Delgado e colaborao do Joo Bueno. Muito obrigada pela ajuda!