Como fazer um bom README

github 13 de Jul de 2020
Guia Rocketseat para um README de qualidade
NLW Expert | Evento gratuito de programação na prática | Rocketseat
Desafie-se em uma nova tecnologia criando um projeto completo em 3 aulas no maior evento online e gratuito de programação na prática para todos os níveis da Rocketseat.

Se você não leu o post O que é README recomendo que leia, se já sabe da importância desse arquivo no projeto, pode continuar por aqui.

Vamos aprender como estruturar um bom README. No final vou deixar um template baseado no que vamos aprender e indicar referências interessantes que encontrei sobre o assunto.

Separei em duas categorias: opcional e obrigatório. Na descrição de cada item vou especificar em qual categoria ele se encaixa. Confere aí.

Estrutura do README

Essa é uma sugestão de estrutura, cada um pode fazer conforme a necessidade do projeto. Vamos agora cobrir cada um dos tópicos da estrutura e outros pontos adicionais.

✅ Logo ou Banner

Status: Opcional

Se seu projeto já tem uma logo adicione no README. Pode ser um banner também. Você pode criar uma logo ou banner usando o Canva.

A logo ou banner podem substituir o título, mas não a descrição do projeto, veja um exemplo. O bom de manter o título e descrição em texto é que ajuda no SEO do Github, o Google vai ajudar indexar melhor seu projeto nas primeiras páginas de pesquisas, além de dar um resumo sobre o seu projeto.

Exemplos de projetos com logo e banner.

NLW Expert | Evento gratuito de programação na prática | Rocketseat
Desafie-se em uma nova tecnologia criando um projeto completo em 3 aulas no maior evento online e gratuito de programação na prática para todos os níveis da Rocketseat.

Título e Descrição

Status: Obrigatório

Título: Nome curto do projeto

Descrição: Uma breve descrição do objetivo do projeto.

# Nome do Projeto 
ou
<h1 align="center">Nome do Projeto</h1>

Nome do Projeto

Com a descrição:

## Descrição do Projeto
<p align="center">Escrever uma breve descrição</p>

Escrever uma breve descrição

<h1 align="center">
    <a href="https://pt-br.reactjs.org/">🔗 React</a>
</h1>
<p align="center">🚀 lib para construir interfaces do usuário com componentes reutilizáveis</p>

🔗 React

🚀 lib para construir interfaces do usuário com componentes reutilizáveis

✅ Badges

Status: Opcional

É uma questão de gosto pessoal e comunicação. As badges são úteis para indicar o status do projeto: você pode colocar a versão dele, link para licença, quantidade de issues, status da build, status dos testes.  Vale muito a pena colocar.

As badges podem ficar no topo antes do título ou abaixo da descrição.

Use o site shields.io para gerar suas badges.

https://blog.rocketseat.com.br/content/images/2020/07/como-escreve-um-bom-read-me-image-1.png

Você pode criar a sua própria badge:

Os ícones de várias logos de produtos e tecnologias você encontra aqui: simpleicons.org.

Podemos customizar partir da URL a abaixo:

https://img.shields.io/static/v1?label=<LABEL>&message=<MESSAGE>&color=<COLOR>&style=<STYLE>&logo=<LOGO>

Os parâmetros significam:

  • LABEL: texto do campo esquerdo
  • MESSAGE: texto do campo direto
  • COLOR: cor do campo direito, pode usar RGB.
  • STYLE: estilo do badge inteiro. Podemos ter: plastic, flat, for-the-badge, social ou flat-square. Teste cada uma delas.
  • LOGO: logo do campo esquerdo

Como exemplo, vou escolher os seguintes parâmetros:

  • LABEL: como Blog
  • MESSAGE: como Rocketseat
  • COLOR: 7159c1
  • STYLE: como for-the-badge
  • LOGO: como GHOST

Podemos colocar ele no README assim em HTML:

<img src="https://img.shields.io/static/v1?label=Blog&message=Rocketseat&color=7159c1&style=for-the-badge&logo=ghost"/>

ou ainda em Markdown:

![Badge](https://img.shields.io/badge/Blog-Rocketseat-%237159c1?style=for-the-badge&logo=ghost)

Pronto. Veja como ficou o badge personalizado:

Legal que no site shields.io tem o input search / project URL que você cola o link do projeto do seu Github e ele sugere alguns badges.

https://blog.rocketseat.com.br/content/images/2020/07/como-escreve-um-bom-read-me-shields.png

Tem esse repositório com algumas badges prontas: Naereen/badges

NLW Expert | Evento gratuito de programação na prática | Rocketseat
Desafie-se em uma nova tecnologia criando um projeto completo em 3 aulas no maior evento online e gratuito de programação na prática para todos os níveis da Rocketseat.

✅ Tabela de Conteúdos

Status: Obrigatório

É ótimo colocar os índices de conteúdos, que é tabela onde a pessoa clica e vai para o tópico específico.

Exemplo com markdown:

Tabela de conteúdos
=================
<!--ts-->
   * [Sobre](#Sobre)
   * [Tabela de Conteudo](#tabela-de-conteudo)
   * [Instalação](#instalacao)
   * [Como usar](#como-usar)
      * [Pre Requisitos](#pre-requisitos)
      * [Local files](#local-files)
      * [Remote files](#remote-files)
      * [Multiple files](#multiple-files)
      * [Combo](#combo)
   * [Tests](#testes)
   * [Tecnologias](#tecnologias)
<!--te-->
https://github.com/ekalinin/github-markdown-toc#table-of-contents

Resultado:

Tabela de conteúdos

Se o README tiver poucos tópicos pode fazer inline, com HTML:

<p align="center">
 <a href="#objetivo">Objetivo</a> •
 <a href="#roadmap">Roadmap</a> • 
 <a href="#tecnologias">Tecnologias</a> • 
 <a href="#contribuicao">Contribuição</a> • 
 <a href="#licenc-a">Licença</a> • 
 <a href="#autor">Autor</a>
</p>
https://github.com/animavita/animavita

Resultado:

ObjetivoRoadmapTecnologiasContribuiçãoLicençaAutor

No README.md do Github você pode usar HTML o que ajuda muito. 👌

✅ Status do Projeto

Status: Obrigatório

Indica se o projeto está em desenvolvimento ou já foi concluído.

<h4 align="center"> 
	🚧  React Select 🚀 Em construção...  🚧
</h4>

Resultado:

🚧 React Select 🚀 Em construção... 🚧

✅ Features

Status: Opcional

Você pode listar as funcionalidades da aplicação.

É opcional, porém é muito importante colocar. Isso ajuda demais as pessoas entenderem o que já tem feito, se estiver em construção você vai checkando o que está pronto.

Exemplo:

### Features

- [x] Cadastro de usuário
- [x] Cadastro de cliente
- [ ] Cadastro de produtos

No Github ou gist fica com essa aparência abaixo. Resultado:

https://blog.rocketseat.com.br/content/images/2020/07/Screen-Shot-2020-07-10-at-14.03.41.png

✅ Demonstração da aplicação

Status: Opcional

Se for um projeto web e estiver hospedado em algum lugar, forneça o link. Se o deploy foi feito no Netlify tem um badge para isso.

Se for uma API backend pode customizar um badge com um ícone do heroku. Pode também colocar o arquivo do Insomnia para ficar mais rápido para o usuário testar a API — Fica muito bom.

Se a aplicação estiver em desenvolvimento, se for um app mobile ou website coloque os prints da tela ou um gif ilustrando a utilização.

Exemplos de como usar imagens e gifs no README:

animavita/animavita
Trigger life-saving alerts, register animals for adoption and find the closest pet friend to adopt :dog: - animavita/animavita
tgmarinho/meetapp
Final Challenge of Rocketseat Bootcamp | Meetapp Backend, Frontend and Mobile - tgmarinho/meetapp
lukemorales/rocketshoes-react-native
NetShoes Clone with React Native and Redux. Contribute to lukemorales/rocketshoes-react-native development by creating an account on GitHub.

A maneira mais segura de manter os arquivos é criar uma pasta screenshots, github, assets, resources ou nome que você quiser e deixar os arquivos nela. Se você usar um CDN de imagens ou gif pode funcionar mas corre o risco do quebrar o link algum dia.

Supondo que você tenha criado uma pasta assets no seu projeto e tem o arquivo banner.png, é assim que você pode adicionar a imagem:

<h1 align="center">
  <img alt="NextLevelWeek" title="#NextLevelWeek" src="./assets/banner.png" />
</h1>

Resultado:

https://github.com/tgmarinho/Ecoleta/blob/master/assets/banner.png?raw=true

Exemplo de como adicionar um banner com markdown:

![Thiago Marinho](https://pbs.twimg.com/profile_banners/41742474/1490016588/1500x500)

Nesse caso estou usando algo genérico, usando uma imagem minha do banner do meu perfil no Twitter.

Outra maneira:

* SignUp Mobile

![SignUp Mobile](screenshots/signup-mobile.png)

Eu prefiro usar as tags HTML porque permitem customizar melhor, centralizar e diminuir a imagem.

Se quiser arriscar com algum serviço de hospedagem tem essa opção: imgur.com, se for um gif pode usar esse aqui giphy.com.

NLW Expert | Evento gratuito de programação na prática | Rocketseat
Desafie-se em uma nova tecnologia criando um projeto completo em 3 aulas no maior evento online e gratuito de programação na prática para todos os níveis da Rocketseat.

✅ Pré-requisitos e como rodar a aplicação/testes

Status: Obrigatório

Se o projeto for uma lib, você tem que mostrar os passos de como instalar e usar a lib, se for um projeto backend | web | mobile | desktop descreva os passos de como fazer para rodar na máquina.

Se tiver testes é bom descrever como rodar os testes.

Exemplo:

### Pré-requisitos

Antes de começar, você vai precisar ter instalado em sua máquina as seguintes ferramentas:
[Git](https://git-scm.com), [Node.js](https://nodejs.org/en/). 
Além disto é bom ter um editor para trabalhar com o código como [VSCode](https://code.visualstudio.com/)

### 🎲 Rodando o Back End (servidor)

```bash
# Clone este repositório
$ git clone <https://github.com/tgmarinho/nlw1>

# Acesse a pasta do projeto no terminal/cmd
$ cd nlw1

# Vá para a pasta server
$ cd server

# Instale as dependências
$ npm install

# Execute a aplicação em modo de desenvolvimento
$ npm run dev:server

# O servidor inciará na porta:3333 - acesse <http://localhost:3333>
```

✨ Resultado:

Pré-requisitos

Antes de começar, você vai precisar ter instalado em sua máquina as seguintes ferramentas:
Git, Node.js.
Além disto é bom ter um editor para trabalhar com o código como VSCode

🎲 Rodando o Back End (servidor)

# Clone este repositório
$ git clone <https://github.com/tgmarinho/nlw1>

# Acesse a pasta do projeto no terminal/cmd
$ cd nlw1

# Vá para a pasta server
$ cd server

# Instale as dependências
$ npm install

# Execute a aplicação em modo de desenvolvimento
$ npm run dev:server

# O servidor inciará na porta:3333 - acesse <http://localhost:3333> 

NLW Expert | Evento gratuito de programação na prática | Rocketseat
Desafie-se em uma nova tecnologia criando um projeto completo em 3 aulas no maior evento online e gratuito de programação na prática para todos os níveis da Rocketseat.

✅ Tecnologias utilizadas

Status: Obrigatório para projetos de portfólio/estudos.

Listar as tecnologias e colocar os links para o seus respectivos sites é um plus no README.

### 🛠 Tecnologias

As seguintes ferramentas foram usadas na construção do projeto:

- [Expo](https://expo.io/)
- [Node.js](https://nodejs.org/en/)
- [React](https://pt-br.reactjs.org/)
- [React Native](https://reactnative.dev/)
- [TypeScript](https://www.typescriptlang.org/)

Resultado:

🛠 Tecnologias

As seguintes ferramentas foram usadas na construção do projeto:

✅ Contribuição

Status: Opcional

Se seu projeto começar a receber contribuições, uma maneira legal de reconhecer o trabalho dessas pessoas é adicionando na lista de contribuidores.

Com certeza eles contribuíram porque gostam do projeto, e vão amar ♥️ receber esse esse reconhecimento.

Segue um modelo bem legal:

Eles utilizaram um bot pra criar essa lista: https://allcontributors.org/docs/en/bot/overview

Mas se não usar algo complexo, pode fazer simples: Link para exemplo.

Resultado:

É bom colocar o arquivo CONTRIBUTING.md na raiz do projeto para os devs saberem os passos de como contribuir no projeto.

✅ Autor

Status: Obrigatório

Aqui entra seu jabá, interessante colocar seus contatos, redes sociais para as pessoas te encontrarem e começar um networking:

Link com o template de exemplo.

Resultado:

✅ Licença

Status: Obrigatório

Precisa definir a licença do seu projeto. Se você não souber definir, leia isso e isto.

A maioria dos devs utilizam a licença MIT que permite as pessoas baixarem o projeto e modificar e você não será responsabilizado por nada.

Muito simples escolher uma licença, o github te ajuda com isso te dando um template.

Geralmente você cria um arquivo LICENSE.

Exemplo:

MIT License

Copyright (c) <2020> <Seu Nome>

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

E se quiser pode usar o Badge também:

GitHub

✅ Emojis

Status: Opcional

Vamos falar ainda sobre Emojis que estão bem na moda. Tem gente que não gosta, mas eles dão emoção ao texto e deixam o visual mais caprichado, porém não pode exagerar.

Fica legal colocar nos tópicos ou nas listas. Exemplo:

🏁 Tópicos

👉  Descrição do projeto

👉 Funcionalidades

👉  Deploy da Aplicação

👉  Pré-requisitos

👉 Como rodar a aplicação

Você pode pegar os emojis aqui ou aqui.

⚒️  Ferramentas:

Sites que dão dicas e inclusive um code/preview do README para seu projeto:

NLW Expert | Evento gratuito de programação na prática | Rocketseat
Desafie-se em uma nova tecnologia criando um projeto completo em 3 aulas no maior evento online e gratuito de programação na prática para todos os níveis da Rocketseat.

Conclusão

Escrever o README português ou inglês? Depende do objetivo do projeto, se for um portfólio e você está procurando emprego na gringa, tem que ser em inglês. Se for uma uma lib que pode ser usada por todo mundo, é interessante escrever em inglês, sua ferramenta vai ter mais alcance e relevância.

Se estiver começando no mundo da programação e não sabe inglês, faça em português mesmo, esse é o seu momento, mas estude inglês.

Dá para escrever em outros idiomas também, mas ai você pode pedir colaboração para isso, claro! Pode ter um README-en.md, ou seja internacionalizar o README e fornecer os links no README principal.

Se o projeto for algum portfólio para mostrar para alguma empresa aqui no Brasil pode ser em português mesmo. Depende do foco, momento e objetivo do projeto.

🎁 Template

Utilize esse template que preparamos para você construir o seu README. 💝

Para copiar a estrutura do README você tem que clicar no arquivo README.md e depois clicar na opção RAW, selecionar tudo, copiar e colar no seu editor preferido que suporte HTML e Markdown.

➕ Mais sobre o assunto e outros aspectos interessantes:

Posta aí nos comentários o seu README bonitão :)

Espero que  tenha curtido! 💜

O aprendizado é contínuo e sempre haverá um próximo nível!

Marcadores

Thiago Marinho

Dev Apaixonado por Tecnologia & Educação! Evolua rápido como a tecnologia, aprendizado é contínuo e sempre haverá um próximo nível. Boost Yourself! 🚀