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

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.

Software
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

EVENTO ONLINE

Simplificando seus projetos de Internet das coisas com o iMCP HT32SX Sigfox

DATA: 18/05 às 15:00h