LEIA-ME ou te devoro: Como escrever um bom README
Tags: braziliandevs, githubbrasil, opensource, tutorial
Published: 2023-03-23 18:26:56

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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/6jcx4w7v87pe4dsa92lp.png)

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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ml6gmrwcl13811cyomqd.png)  

### 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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/zflhl5blk4nk4fnhvvm2.png)

  

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](https://docs.github.com/pt/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors), 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](https://docs.github.com/pt/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository) para não ter problemas futuros

![lista de licenças opensource](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ql0vjbnqbkm41jdhftgb.png)

### 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/](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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/txcx5lr7cyrn0xgtpij0.png)
  

## 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 🥑**