Documentar ou não documentar o código não é exatamente um consenso na comunidade. Muita gente diz que um código bem escrito é a própria documentação. O argumento contrário diz que se você é capaz de escrever um código legível, então você é capaz de documentá-lo. Ter uma documentação adequada do projeto (que é diferente de comentários soltos ao longo do código) ajuda tanto no onboarding de novos devs (é mais fácil entender como o projeto funciona quando tudo já está documentado) quanto para refatorar códigos que foram escritos já a algum tempo, evitando que ele se torne legado.

Documentation As Code

DaC é uma forma de automatizar a escrita da documentação com as mesmas ferramentas do código que está sendo escrito. Desta forma, a documentação vai sendo escrita junto do código e ao mesmo tempo do código, o que torna a documentação um organismo vivo e continuamente atualizado. Uma das formas de se criar e manter esta documentação é justamente a colocando nos arquivos de código na forma de um comentário especiais (com marcações próprias) que podem ser extraídos por um framework especifico que gera a documentação 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 próprios frameworks de documentação, como por exemplo o PHPDoc, o Swagger do Java e o Sphinx, do Python.

A documentação geralmente é escrita na forma de um comentário no próprio código com uma marcação e depois é exportada automaticamente para um documento, que pode ser lido pelo time de desenvolvimento, de produto e até mesmo por usuários (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 orientação a objeto, a parte principal será uma classe, e a parte auxiliar será um método. Em programação funcional, a parte principal e as auxiliares serão funções, então descreva a main e explique a utilidade das funções utilizadas na main.

Outro ponto é que a documentação deve falar do negócio, e não do código. Um código bom e limpo é auto-explicável. A função da documentação é explicar a regra de negócio por trás dele e não o código em si.

Como escrever?

Eu pessoalmente acho que cada trecho de documentação deve caber em um tweet. A idéia não é escrever um artigo para cada parte, apenas ajudar a explicar o que acontece ali. No entanto, aqui é interessante procurar os padrões da comunidade da linguagem que você usa. Em Python, o padrão é ser mais extenso e, em alguns casos, até embutir testes nas docstrings.
Tenha sempre em vista quem vai ler a documentação. Se na sua equipe as pessoas de produto e operações também terão acesso ao documento, não é tão legal usar linguagem técnica demais.

O que não documentar?

Algumas coisas devem ser explicadas a nível de código, e não deveriam ir para a documentação do produto por referenciarem apenas a utilização de um código que não é auto explicável (como por exemplo uma RegExp). Quaisquer comentário que só faça sentido junto ao código não deve ir para a documentação. Todos, de forma geral, são uma prática ruim e não devem nunca ir para a documentação (ou produção).

Seguindo o mapa da mina

Caso seu time esteja adotando a escrita de documentação, veja esse texto como um mapa da mina, que vai auxiliar todos a chegar mais rápido nas especificações do software. Escreva com atenção, mantenha o documento sempre atualizado e o mais importante: leia sempre, isso vai te ajudar bastante (especialmente em refatorações).

Para escrever este texto eu tive a revisão do João Bueno e do Caio Delgado e colaboração do João Bueno. Muito obrigada pela ajuda!