Do começo

Aqui vai um pouco de contexto como como eu cheguei as conclusões que vou falar daqui a pouco. Se quiser pular essa parte, vá direto para o Better read-me's

Acho que uma das coisas que não posso negar sobre ter passado 2 anos e meio trabalhando no Nubank é que lá foi uma grande escola de boas práticas. Tanto para aprender uma técnica nova quanto pra consolidar práticas que eu já adotava de alguma forma lá era um ambiente que sempre me trazia a oportunidade de aperfeiçoar alguma técnica. Uma dessas técnicas é sobre documentar documentar e documentar. Escrever e manter documentações talvez tenha sido uma das coisas que eu mais aprendi/aperfeiçoei nesses anos.

Como bom dev, eu sempre me preocupei mais me documentar fluxos e, de alguma forma, tinha um pouco em mim o ceticismo de que manter documentação era algo complexo. Certamente hoje eu vejo isso de uma forma totalmente diferente. Pra mim, hoje, escrever uma boa documentação - não apenas fluxos, mas também porque e como decisões foram tomadas - é algo muito importante no meu dia-a-dia.

Nesse texto eu poderia falar sobre como manter, ou sobre como não tornar burocracias uma tarefa burocrática, mas acho que não é o meu propósito no momento. Acho que posso até pensar em fazer isso em um outro texto.

Mas em um mundo com milhares de siglas como ADR, RFC, PDR, 6-pager, 1-page... ufa... não podemos deixar de pensar no básico como desenvolvedores: o bom e velho read-me escrito com o maravilhoso Markdown.

Aqui vale lembrar que nenhuma dessas documentações será substituída pelo Read-me e nem que todas essas documentações serão usadas o tempo todo. Vamos lembrar que todas são ferramentas e ferramentas devem ser usadas pra resolver problemas específicos.

Bom... Então vamos ao que interessa. O Read-me.

Twitter... fale comigo

Eu já tentei diversos modelos de read-me's no passar dos anos e acho que isso é algo que sempre estará em mutação. Mas pra buscar não ser tão enviesado com meu gosto pessoal do que eu gostaria que tivesse nessa documentação, eu resolvi falar com a minha bolha... a famigerada bolha tech. E pra isso eu abri essa thread aqui no twitter.

E com isso eu consegui entender o que as pessoas viam de valor no read-me de um projeto e com isso eu tentei consolidar o seguinte pros meus projetos (pessoais e da empresa).

Better read-me's

Bom... aqui eu começo fazendo um apelo. Por favor... por favor meesmo... não deixem o projeto sem o mínimo de informação no Read-me ou com a documentação padrão gerada pelo framework que você tá usando.

Feito esse apelo, vamos ao que interessa.

Comece pelo básico

Algumas informações são essenciais para que as pessoas minimamente entendam o que o seu projeto está fazendo e deveriam estar em todo README como o mínimo aceitável.

O nome do projeto
Uma breve descrição do projeto (mesmo que você repita isso no About do Github)
E comandos importantes que possam ser executados no projeto.

Com esse mínimo, você vai tirar as pessoas da mais completa zona de escuridão e vai permitir que ela tenha um entendimento básico do escopo do projeto e vai saber o que ela precisa fazer pra rodar o projeto.

Nesse contexto mínimo ainda vale adicionar uma área para dependências (sejam elas quais forem) para rodar/testar o projeto.

Veja um exemplo de README enxuto aqui https://gist.github.com/marcopollivier/7d4a378332f23d5c6302abc357848064#file-readme_minimo-md

Vá além do básico

O modelo anterior é o mínimo que um projeto deveria ter. Nenhum projeto novo que será usado por outra pessoa - ou por você mesmo no futuro - deveria ter menos do que isso.

Porém se você quiser ir um pouco mais além, existem outras informações que também não são complexas de manter e que proporcionarão um maior suporte ao seu projeto. São elas:

Toda a lista anterior (obviamente);
Principais funcionalidades
Breve desenho da arquitetura (especialmente as principais integrações. Para esse ponto, recomendo fortemente utilizar a integração entre Github e Mermaid)
Características relevantes como latência, escalabilidade e segurança
Links para documentações e links de referências

README campeão

O modelo anterior já podemos entender que será um excelente apoio para quem está chegando no repositório pela primeira vez. Mas vale lembrar que com o advento dos micro-serviços, a gestão ficou muito mais granular e complexa de manter. Então, para um readme campeão, esse ponto precisa ser levado em conta. E para isso, busque chegar a esse modelo final, adicionado os seguintes tópicos ao anteriores:

O Contexto de criação do projeto/serviço
Quais problemas tentam ser resolvidos
O escopo do projeto (para qual finalidade ele foi pensado e o que ele NÃO vai atender) e
Alternativas que poderiam ser usadas no lugar desse projeto e porque não foram usadas.

Ah... use e abuse de tags como essas

Essas tags podem ser usadas tanto para métricas básicas como ferramentas para ajudar a criar links para documentações, boards e etc.

No fim, seu README campeão vai ficar parecido com esse aqui https://gist.github.com/marcopollivier/7d4a378332f23d5c6302abc357848064#file-readme_campeao-md

Considerações finais

Escrever e manter uma boa documentação é tão importante quanto escrever e manter um bom código. Se você não faz um dos dois, existe a grande possibilidade de você também negligenciar o outro. Documentações são uma forma de você dar contexto histórico ao que estava acontecendo em um determinado momento para que pessoas no futuro entendam o motivo das decisões tomadas. Além de ser uma excelente ferramenta de performance. Isso mesmo que você escutou. As pessoas associam a criação de documentação como algo burocrático, tedioso e que toma tempo. Mas quando você escreve o mínimo (como mostrei aqui nesse texto), as próximas pessoas que precisarem entender, ganharão um tempo absurdo no entendimento do que o projeto ou serviço se propõe. Escrever documentação faz parte da rotina de um bom Engenheiro de Softwares. Escrever documentação faz parte do processo de amadurecimento de qualquer profissional.

Blog

READMEs: o primeiro passo para uma boa documentação

Marco Ollivier