DEV Community

Cover image for LEIA-ME ou te devoro: Como escrever um bom README
Pachi 🥑 for GitHub

Posted on • Edited on

LEIA-ME ou te devoro: Como escrever um bom README

Que título dramático, você deve está pensando… Mas eu não resisti e tiver que usar essa frase.
Até porque READMEs são feitos para, como o nome diz, serem lidos, e se você tentar contribuir ou usar um projeto open source sem ler esse documento, você pode ser, metaforicamente, devorada por dúvidas.

Hoje escolhi falar sobre READ.ME porque essa é a página inicial de qualquer projeto open source, desde de um framework famoso como o React,js, até daquela calculadora que você fez pra praticar seus conhecimentos de programação.

O que é um README e porque eu deveria me importar?

Mas o que é o README? O nome, traduzido para o português fica como LEIAME, o que já dá a dica de que é um documento que deve ser lido. Mas, por que?

O README é um arquivo em markdown (.md) que é considerado o manual de instruções do seu projeto. Ele tem que conter informações úteis para que outras pessoas possam entender, contribuir e usar seu projeto, apenas lendo esse arquivo.

Você deveria se importar porque esse é o primeiro arquivo que as pessoas vão ler no seu projeto! Ter um bom README também ajuda seu projeto a ter destaque, já que outros projetos muitas vezes não tem um bom README.

Como criar o arquivo README

Direto pelo GitHub

Primeiro vamos as tecnicalidades. Tem várias formas de se criar um README.

A primeira é quando você criar seu novo projeto no GitHub, na página de criação você vai encontrar o texto Inicialize esse repositório com, e Add um arquivo README é a primeira opção. Você pode clicar na caixinha aqui e seu projeto já vai ser criado com um README:

print da parte da pagina de criação de repositorio mencioanda acima

Isso vai criar no root do seu repositório o arquivo README.md e o conteúdo desse arquivo é o que aparece na página inicial do repo.

O README criado aqui é bem básico, mas neste artigo vou ensinar como deixar ele mais completo.

repositorio com readme vazio

Criar manualmente

Se você já tem um projeto criado, ou quer criar o README manualmente, tudo que você tem que fazer é criar um arquivo com o nome README.md no root do projeto, por onde você preferir (terminal, IDE, pelo GitHub mesmo).

Na imagem abaixo, você pode ver o exemplo de um REAME sendo criado dentro da pasta leiame pelo terminal do Git

terminal criando arquivo com comando touch

Agora que já temos nosso arquivo criado, vamos editá-lo com os itens necessários?

Editando seu README

O arquivo README pode conter diversas informações sobre o seu projeto e muitos desses itens vão ser opcionais, mas um bom README deve ter, no mínimo, o título do projeto e uma boa descrição, como instalar e rodar o projeto, como usar, como contribuir e a licença dele.

Vamos falar sobre cada um desses itens.

Título e Descrição

O título tem que ser algo curto, mas o mais descritivo possível, para ajudar as pessoas a entenderem qual o objetivo principal do projeto.

Já a descrição complementa o título: O que o projeto faz e para que serve? Quais as tecnologias usadas neste projeto? Você pode adicionar também desafios que você teve criando projetos e features que espera adicionar no futuro.

Ouso dizer que a descrição é a parte mais importante de qualquer README, então dedique um carinho especial para essa sessão <3

Como Instalar e Rodar o projeto

Esse item não se aplica a todos os projetos, mas seu projeto é algo que as pessoas têm que instalar e rodar localmente, isso é algo super importante.

Aqui você deve incluir um passo-a-passo detalhado de como instalar o projeto e tudo que é necessário para fazer o ambiente de desenvolvimento rodar sem problemas.

Como Usar o projeto

Escreva aqui instruções de como usar seu projeto e adicione exemplos de como ele já foi usado (uma ótima dica é pedir para quem já usa o projeto contribuir nessa sessão).

Aqui é legal adicionar visuais, como prints do projeto funcionando e qualquer outra coisa que você considere interessante e relevante.

Como Contribuir

Projetos Open Source geralmente estão sempre aceitando contribuições (esse é, afinal, o apelo principal de Open Source), então é bom ter um guia de contribuições. Se uma pessoa quiser contribuir, o que ela deve fazer?

Apenas dar um Fork e criar uma PR ou ela precisa criar uma issue primeiro?

Temos um guia de diretrizes de contribuição, caso você queira inspiração.

Licença

Quando você criar um novo repositório no GitHub, vão te perguntar que licença você quer usar.

A licença diz às pessoas o que elas podem e o que elas não podem fazer com o seu código, como alterar, usar e distribuir.

Existem várias e eu geralmente vejo projetos pequenos usando a MIT. Mas se você tem grandes ambições para seu projeto, recomendo pesquisar mais sobre licenças para não ter problemas futuros

lista de licenças opensource

Itens opcionais

Os itens acima são os que eu considero essenciais para um README bem feito, mas você sempre pode melhorar.

Como itens opcionais temos:

  • Uma tabela de conteúdo, caso seu README fique muito extenso, é um bom item para facilitar a leitura.

  • Créditos, (caso você teve ajuda ou se inspirou em algum outro projeto ou pessoa, é sempre legal dar crédito a quem merece.

  • Badges são um ótimo visual, e existem todos os tipos de badge. Você só tem que ir no https://shields.io/, copiar o código da badge deseja e adicioná-la ao seu repo. Você pode usar uma badge para demonstrar qual a licença do projeto, por exemplo:

lista de licenças em formato badge

DESAFIO: Vamos criar um README?

Isso é tudo que eu tinha para vocês hoje, e quero deixar aqui um desafio: Vá em algum dos projetos que você já tem no GitHub e crie um README bonitinho.

Depois vem aqui e comenta com o Link do repositório para eu ver!

Você também pode compartilhar nas redes sociais se preferir, mas por favor mencione esse artigo <3

Obrigada por ler até aqui,

Pachi 🥑

Top comments (10)

Collapse
 
vanessatelles profile image
Vanessa Telles

Um README bem feito faz toda diferença já me deparei com vários repositórios ótimos, mas que não chamavam atenção por pecarem na apresentação.

Collapse
 
pachicodes profile image
Pachi 🥑

muito bom!

Collapse
 
pachicodes profile image
Pachi 🥑

Sim! faz muita diferença!

Collapse
 
lelepg profile image
Letícia Pegoraro Garcez

Artigo maravilhoso como sempre, Pachi. Os arquivos README sem dúvida são uma parte essêncial do projeto.

E uma dica extra caso o README do seu projeto fique grande demais: utilizar o recurso de Wikis do Gihtub. Eu conheci esse recurso ultimamente e é algo que eu tenho tentado explorar.

Collapse
 
heliomarpm profile image
Heliomar P. Marques

Tenho tentado deixar todos os meus repos com esse padrão.

github.com/heliomarpm/udemy-downlo...
github.com/heliomarpm/electron-qui...

Collapse
 
pachicodes profile image
Pachi 🥑

Isso ai!

Collapse
 
easbarba profile image
Alexander Barbosa

bacana!

Collapse
 
eduardoklosowski profile image
Eduardo Klosowski

Tinha uma época que só falavam de HTML semântico, atualmente torço pela época do Markdown semântico, que vejo muitos não usarem os elementos corretos do Markdown.

Collapse
 
vinnysilveira profile image
Vinicius Silveira

Esse é o meu, escrevi antes de ler este POST, hehehe! github.com/vinny-silveira/screeps-...

Collapse
 
alejandro_garcia profile image
Lacalculadoradealicia dealicia

La Calculadora de Alicia es una herramienta digital diseñada para facilitar cálculos de manera rápida y eficiente. Ofrece una amplia gama de funciones, desde operaciones matemáticas básicas hasta cálculos avanzados en áreas como trigonometría y finanzas. Su interfaz amigable permite que usuarios de todos los niveles, desde estudiantes hasta profesionales, realicen cálculos con precisión y sin complicaciones. Además, la Calculadora de Alicia está disponible en diferentes dispositivos, asegurando accesibilidad y comodidad. Con un enfoque en la seguridad de los datos, esta calculadora se convierte en un recurso esencial para quienes buscan optimizar su tiempo y mejorar su productividad en tareas diarias.