O que escrever num README?

Capa Embarcados

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.

Arquivo README.md na página inicial do cayman.
Figura 1 – Arquivo README.md na página inicial do cayman, um dos temas para GitHub Pages , que também aceita arquivos de extensão .md para postagem de blog.

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

 

Depende da estratégia de marketing da sua marca pessoal. Poderá escrever “apelido+nome real+email” para deixar o documento mais formal.

Referências

[1] Licensing a repository – GitHub

[2] Ten Steps to a Better README – Mike Jang (Ignite OSCON 2015)

[3] Write the Readable README – Daniel D. Beck

[4] Contributing Template – Nadia Eghbal

[5] Write the Docs Community

Website | Veja + conteúdo

Formado em Engenharia Elétrica na UNESP de Guaratinguetá. Curte animes, seriados, rock, esportes, tecnologia, etc. Um menino prendado.

Licença Creative Commons Esta obra está licenciada com uma Licença Creative Commons Atribuição-CompartilhaIgual 4.0 Internacional.

Receba os melhores conteúdos sobre sistemas eletrônicos embarcados, dicas, tutoriais e promoções.

Comentários:
Notificações
Notificar
guest
1 Comentário
recentes
antigos mais votados
Inline Feedbacks
View all comments
Fernando Ventura Jr
Fernando Ventura Jr
02/02/2020 16:29

“Título e breve descrição do projetoNo 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. https://www.embarcados.com.br/o-que-escrever-num-readme/

No trecho acima, o que seria uma PLACA? Você não quer dizer algo com a plataforma de desenvolvimento? Algo como Java 8, usando a IDE Eclipse e as bibliotecas….

Talvez você goste:

Séries

Menu