O que escrever num README?

Mesmo com a demanda de desenvolvimento de códigos que exigem dinâmica de documentação mais ágil, o arquivo README continua sendo um dos principais documentos de um projeto de software. Mas o que escrever exatamente?

A resposta pode ser: “depende”. Em uma empresa, o uso de uma ferramenta é tão comum que o time pode achar desnecessário citar o uso dela no arquivo README. Para chamar a atenção de um público ou focar numa comunidade de desenvolvedores, pode-se destacar um ponto em detrimento do outro.

Com o uso cada vez mais frequente de plataformas abertas como o GitHub, o arquivo README está deixando de ser apenas um documento e servindo também como um cartão de visita. E, para tal, alguns pontos são essenciais para o propósito principal de divulgação.

Já deixo claro aqui que o texto foi pensado para quem escreve algum tipo de código para sistemas embarcados. Algumas opiniões enviesadas vão aparecer e caso você discorde em algum ponto ou acredita que um tópico ficou batido, deixe nos comentários a sua opinião!

Então, o que escrever?

• Título e breve descrição do projeto

No título ou na descrição você pode colocar o número da versão do projeto, como também a placa de desenvolvimento usada.

Se houverem outros detalhes ou até mesmo um pdf com a descrição completa, pode-se deixar links para os mesmos. Caso você use GitHub, uma boa opção é utilizar-se de wikis.

• Pré-requisitos

Como num artigo científico, deve-se descrever as ferramentas usadas: qual compilador, biblioteca, IDE, sistema operacional, etc. foram usados? Caso contrário o código pode ser visto como algo que funciona somente na teoria e não vai atrair a atenção de quem está lendo.

Entretanto não precisa ser um tutorial passo a passo. Devemos lembrar que o sucesso da replicação depende também das habilidades técnicas de quem vai clonar o código. Mas se você tem um coração de mãe, poderá deixar links para tutoriais.

• Guia de instalação

É preciso definir variáveis de ambiente no sistema operacional? É pra deixar tudo na variável PATH? Qual é o comando para compilar usando o makefile fornecido? Existem outros comandos implementados no makefile? Existe alguma ferramenta a ser instalada de forma especial?

• Licença

Quando se trata de de projetos Open Source, é uma descrição de extrema importância.

A melhor opção para não deixar visualmente poluído é escrever em uma sentença a qual licença pertence e o link para o documento LICENSE.txt.

Existem diversos tipos de licença: MIT, BSD, LGPL2, LGPL3, etc. O GitHub fez uma página explicando a diferença entre as licenças, como também o Open Source Guide dá dicas adicionais para escolher a licença correta para o seu projeto. Este relatório técnico do IME-USP informa sobre as licenças, suas vantagens e desvantagens.

• Autoria e contribuições

Além do seu próprio nome, é bom constar a ajuda de outras pessoas e institutos que estão contribuindo de alguma forma com o desenvolvimento do projeto.

Escreva em Markdown!

Markdown é uma sintaxe de extensão .md que é suportado por repositórios como GitHub, Bitbucket e GitLab.

É muito fácil de utilizar, e você pode deixar os títulos e subtítulos em tamanhos variados, deixar o texto em negrito e itálico, utilizar bullet points, etc. Você pode até adicionar figuras e tabelas para vários propósitos. O GitHub fez um guia explicando toda a sua potencialidade.

Outros detalhes

• Linguagem de programação

Uma vez que plataformas como GitHub identificam automaticamente a linguagem, pode parecer desnecessário. Mas talvez você queira colocar “[…] escrito em linguagem C […]” na descrição para evitar pull request escrito em C++.

• Vai resolver algum problema ou é uma solução alternativa?

Às vezes o desenvolvedor está tão focado em escrever o código que acaba se esquecendo de vender o peixe. Por exemplo, se mostrar em qual ponto ou aplicação se difere dos outros códigos, vai acabar recebendo estrelinhas no GitHub.

• Mostrar que funciona

Outra forma de fazer o seu projeto ganhar destaque com o README é incluir no conteúdo  alguma forma de comprovação (a saída no terminal, links para vídeos, etc.) que o seu projeto funciona.

• Documentação automática

Mesmo que você não goste muito de escrever, deve-se evitar scripts para gerar automaticamente textos da descrição, para não parecer tão robótico. Por outro lado, essas ferramentas podem quebrar um galho: “Para obter a documentação completa, digite make pdfdocs no terminal.

• Assinatura com apelido

Referências