Como escrever um README.md sensacional no Github
Tags: github
Published: 2020-05-03 15:16:24


Depois de desenvolver aquele projeto incrível, ter passado vários perrengues com a aplicação e Git, você abriu no Github para a comunidade. 

Mas as suas tarefas não terminaram, está na hora de documentar o seu projeto! E nada melhor do que um bom README.md. 

![Ohh não](https://media.giphy.com/media/LTYT5GTIiAMBa/giphy.gif)

### Tópicos deste artigo
* [O que e o README](#o-que-é-o-readme)
* [Por que usá-lo](#por-que-usálo)
* [Estrutura do README](#estrutura-do-readme)
* [Titulo e descrição do projeto](#titulo-e-descrição-do-projeto)
* [Como usar Badges](#como-usar-badges)
* [Funcionalidades da Aplicação](#escreva-as-principais-coisas-que-a-sua-plataforma-pode-fazer)
* [Emojis](#emojis)
* [Status do projeto](#status-do-projeto)
* [Deploy da aplicação? Oba](#deploy-da-aplicação-oba)
* [Poxa, mas meu projeto ainda não está no ar, e agora?](#poxa-mas-meu-projeto-ainda-não-está-no-ar-e-agora)
* [Imagens](#beleza-mas-como-eu-coloco-imagens)
* [Rodando o seu projeto](#e-se-alguém-quiser-rodar-o-projeto-na-maquina)
* [Dados, dados e mais dados](#dados-dados-e-mais-dados)
* [Como rodar os testes?](#como-rodar-os-testes)
* [Acabou o projeto?](#acabou-o-projeto)
* [Não esqueça dos amiguinhos](#não-esqueça-dos-amiguinhos)
* [Dependências e tecnologias](#dependências-e-tecnologias)
* [Resolvendo problemas](#resolveu-perrengues-durante-a-aplicação-documente)
* [Fechando com chave de ouro](#fechando-com-chave-de-ouro)
* [Deixe a preguiça de lado](#deixe-a-preguiça-de-lado)
* [Presente](#presente)

### **O que é o README**

Ele é basicamente um arquivo de texto que pode ser escrito a partir de tags HTML ou Markdown. Pessoalmente costumo misturar os dois pois usando HTML consigo centralizar os elementos. Neste artigo não vou focar muito em como utilizar essas tags e sim na estrutura da documentação em sí. Se quiserem saber como utilizá-las recomendo este [artigo](https://medium.com/@raullesteves/github-como-fazer-um-readme-md-bonit%C3%A3o-c85c8f154f8) excelente do Raul Esteves. 

### **Por que usá-lo**

Ele é mais que uma forma de documentação, é o **cartão de visita** para o seu projeto e vai fazer com que as pessoas que visitem o seu perfil do Github passem mais tempo olhando o você produziu. 

Neste artigo eu vou recriar o README.md que fiz para o projeto [Certificates for Everyone](https://github.com/React-Bootcamp-WoMarkersCode/certificate-generator/blob/DianaRegina/README.md), mas se você estiver com pressa, já deixo aqui um **resumo** deste artigo: 

### **Estrutura do README**

- Titulo
- Status
- Tabela de Conteúdos
- Descrição
- Layout ou Deploy da aplicação
- Pré-requisitos 
- Dependências e Libs Instaladas 
- Como rodar a aplicação
- Como rodar os testes
- Database 
- Solução de problemas 
- Contribuintes
- Tarefas em aberto
- Licença

A primeira coisa a se pensar é na estrutura dessa documentação, podemos ter algo parecido com:

### **Titulo e descrição do projeto**:  

Coloque o nome do seu projeto. Exemplo:

```
# Titulo 
ou
<h1 align="center"> Titulo </h1>
```

Seguido de uma descrição breve sobre ele:

```
## Descrição do Projeto
<p align="justify"> Escrever descrição, que ficará com texto justificado </p>
```

A tag `align` é usada para alinhar os elementos e assume _left_ por padrão. 

![titulo-descricao](https://user-images.githubusercontent.com/46378210/80870466-fb68bc80-8c7c-11ea-9b7c-456d75fb4656.PNG)

Perceba que aqui eu também inseri uma arte para o meu projeto, que poderia inclusive substituir o titulo. É algo que deixa o README.md mais bonito mas é **completamente opcional**

### **Como usar Badges** 

<img src="https://cdn-media-1.freecodecamp.org/images/pPzFRYVv5jJvht3U-2f8KgGIEoF0yqdxNrAD" width="200">

Badges servem para certificar ou indicar algo do teu projeto como status, licença, linguagens, testes, etc. Para saber mais acessem a [documentação](https://github.com/badges/shields).

Para utilizados podemos entrar o site [shields.oi](https://shields.io/). Lá é possível encontrar vários modelos prontos, mas hoje eu vou mostrar com personalizar um. 

Podemos fazer isso a partir de uma URL como esta:

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

Onde cada parâmetro significa: 

- **LABEL** texto do campo esquerdo 
- **MESSAGE** texto do campo direto
- **COLOR** cor do campo direito (as opções podem ser encontradas no site)
- **STYLE** estilo do badge inteiro. Podemos ter: _plastic_, _flat_, _for-the-badge_, _social_ ou _flat-square_. 
- **LOGO** logo do campo esquerdo

Como exemplo, vou escolher os seguintes parâmetros: 

- **LABEL** como react
- **MESSAGE** como framework
- **COLOR** como blue
- **STYLE** como for-the-badge
- **LOGO** como REACT

Podemos colocar ele no README assim:
```
<img src="https://img.shields.io/static/v1?label=react&message=framework&color=blue&style=for-the-badge&logo=REACT"/>
```
ou ainda:
```
![Badge](https://img.shields.io/static/v1?label=react&message=framework&color=blue&style=for-the-badge&logo=REACT)
```

E tcharam!! Temos um [badge personalizado](https://img.shields.io/static/v1?label=react&message=framework&color=blue&style=for-the-badge&logo=REACT)

Outra mágica do shields é que podemos copiar a URL do projeto no github e colar no campo de busca do site. Em seguida, ele te dará badges personalizados de acordo com o teu repositório:

![badges](https://user-images.githubusercontent.com/46378210/82450366-fed4b400-9a82-11ea-8229-cfba354205cb.PNG)


### **Escreva as principais coisas que a sua plataforma pode fazer** 
Seria bacana listar as principais funcionalidades que sua aplicação oferece a partir de listas, poderíamos fazer de algumas formas:

```
### Listas não ordenadas
- Cadastro de conta com Google
	- Captura de avatar a partir do login ou registro com google

### Usando um task list, marcando tarefa como completada ou não  

- [X] Cadastro de conta com Google
- [ ] Cadastro de conta com Google

### Lista ordenada
1. Listagem ordenada 

```

![lista-funcionalidades](https://user-images.githubusercontent.com/46378210/80871696-1e4a9f00-8c84-11ea-9330-2a1bab3462cb.PNG)

### **Emojis**

Para deixar os títulos e listas mais divertidos costumo acompanhá-los com algum emoji que representam aquele tópico. É possível encontrar vários neste [repositório](https://gist.github.com/rxaviers/7360908). Para usá-los, basta copiar o nome da tag e usar no README.md Exemplo:

```
## O que a plataforma é capaz de fazer :checkered_flag:

:trophy: Gerar PDF do certificado com as informações preenchidas no formulário para cada participantes para envio de e-mail 

:trophy: Check-list de participantes, permitindo selecionar quem irá receber os certificados 

:trophy: Permite que o organizador do evento escreva sua assinatura digital dentro da plataforma
```
E teremos como resultado:

![funcionalidades-emojs](https://user-images.githubusercontent.com/46378210/80871699-1f7bcc00-8c84-11ea-8349-568032a537cb.PNG)

### **Status do projeto**
Indique se seu projeto ainda está em desenvolvimento ou concluído, isso ajuda muito quem acompanha o seus trabalhos. 
```
> Status do Projeto: Concluido :heavy_check_mark:

> Status do Projeto: Em desenvolvimento :warning:
```
![status](https://user-images.githubusercontent.com/46378210/80872965-b5ffbb80-8c8b-11ea-8b6c-344d280c4369.PNG)

### **Deploy da aplicação? Oba**

Se for possível subir a aplicação com [Netlify](https://www.netlify.com/) ou outras plataformas que permitem com que as pessoas acessem o seu projeto sem ter o trabalho de rodar em suas maquinas é ótimo, isso poupa **tempo** e **paciência**. Se tiver, coloque na documentação: 

```
## Deploy da Aplicação com Netlify: :dash:

/* Aqui estamos usando a tag Quotes do markdown*/

> https://certificates-for-everyone-womakerscode.netlify.app/
```
![deploy](https://user-images.githubusercontent.com/46378210/80872493-a8950200-8c88-11ea-8280-b1b28dc3efde.PNG)

### **Poxa, mas meu projeto ainda não está no ar, e agora?**

Já dizia aquele ditado: _"Quem não tem cão caça com gato"_. Aqui é a mesma coisa, coloque _prints_ do layout do projeto (no caso de uma aplicação _frontend_), assim o visitante já poderá ter uma imagem do que você fez.   

### **Beleza, mas como eu coloco imagens?**

Existe o jeito não tão legal de fazer, mas funciona:

1. Abra uma issue
2. Insira uma imagem
3. Um link como este será gerado:
`
![certificado](https://user-images.githubusercontent.com/46378210/80869186-51d1fd00-8c75-11ea-93d3-25485501aa43.png) 
`
4. Copie e cole no README.md e tcharam! A imagem irá aparecer!

A forma mais segura de fazer: 

1. Suba no seu repositório a imagem desejada. Ela ficará junto com os outros arquivos de código.
2. Acesse a imagem e copie a URL, que pode ser algo parecido com: `https://github.com/Diana-ops/womakerscodeReact/blob/master/api-cep/src/assets/background.png`
3. Use uma tag `img` e insira o link em `src`

Também é possível capturar imagens da própria web, usando a URL assim como nesses passos que eu mostrei, mas **isso não é muito seguro**, pois a imagem pode ser deletada posteriormente. 

### **E se alguém quiser rodar o projeto na maquina?**

Esse é um tópicos mais importantes da documentação, principalmente quando falamos de código _open source_. O primeiro passo é escrever os **pré-requesitos** que ele precisa para rodar, como o `yarn`, `npm`, `gem`, `bundle`, etc. 

Depois deixe um **passo a passo** bem bacana para outros devs, indicando todos os comandos de instalação e execução e em que **pasta** executa-los. 

![run-app](https://user-images.githubusercontent.com/46378210/80872495-b2b70080-8c88-11ea-9974-fbd0ab4a8cc3.PNG)

### **Dependências e tecnologias** 

Sobre colocar as linguagens eu já antecipo: **depende**. O próprio Github já indica as linguagens dos arquivos lá no topo do diretório.

![linguagens](https://user-images.githubusercontent.com/46378210/80872557-075a7b80-8c89-11ea-8ce6-e77801adb352.PNG)

Então se já estiver tudo lá, não há necessidade de colocar de novo. Mas caso tenha usado alguma lib extra como React Routes, React PDF, Antdesign é bacana colocar.

Eu não vejo necessidade em se aprofundar em **como instalar** cada uma dessas dependências, pois um `yarn install` ou `bundle` já irão fazer isso e as instruções para instalar cada uma das libs podem ser encontradas na própria documentação. 

O que pode ser feito aqui é utilizar os links dessa forma:

```
## Linguagens e libs utilizadas :books:

- [React PDF](https://react-pdf.org/): versão xx.xxx 
```

![libs](https://user-images.githubusercontent.com/46378210/80872462-7c798100-8c88-11ea-96b2-0833493479b7.PNG)

Assim o visitante verá uma lista de todas as dependências e o link já redireciona para a documentação. Se for o caso, indique a versão necessária para rodar o projeto. 

### **Dados, dados e mais dados**

Caso a sua aplicação conte com um _backend_ ou JSON você pode deixar uma amostra na documentação. Podemos usar tabelas, que são uteis para organizar diversas outras informações. As colunas são divididas pelas barras e o título principal do conteúdo são separados pelos traços. 
 
```
### Participante: 
|name|email|present|receiveCertificate|course|
| -------- | -------- | -------- |-------- | -------- |
|Chaiana Hermes|chaiana_hermes@yahoo.com.br|true|false|Bootcamp React|
```
![json](https://user-images.githubusercontent.com/46378210/80872453-6e2b6500-8c88-11ea-9448-64e215bde098.PNG)

### **Como rodar os testes?**  

Os testes são boas práticas utilizadas em projetos (caso nunca tenha feito, comece já) e independente da linguagem que estiver usando sempre vai ter um comando para executa-los e é importante documentar. Exemplo:
```
/*Para projetos com React*/
$ npm test

/*Para projetos com Rails*/
$ rspec
```
### **Acabou o projeto?**

Pode ser que ainda faltem algumas funcionalidades para serem implementadas ou refatorações em alguma parte do código. Aqui é o momento de listar quais tarefas estão abertas em issues ou no próprio README.md caso esteja aberto para receber contribuições e ajuda. 

### **Não esqueça dos amiguinhos**

Quando fizer aquele projeto em grupo ou receber alguma Pull Request como contribuição destaque-os. Uma coisa bem bacana aqui é misturar imagens com tabelas: 
```
[<img src="https://avatars2.githubusercontent.com/u/46378210?s=400&u=071f7791bb03f8e102d835bdb9c2f0d3d24e8a34&v=" width=115 > <br> <sub> Diana Regina </sub>](https://github.com/Diana-ops) |
| :---: |  
```

Confuso? Calma que eu explico. 

- Dentro de || temos uma tag html `<img>`, nela foi definido o **link** e o **tamanho** da imagem com **src** e **width**. Aqui foi inserido o avatar do dev. 

- Depois temos a tag `<br>`, que faz uma quebra de linha com o próximo elemento colocando-o em baixo da imagem.

- Dentro de `<sub>` colocamos o nome dele. 

- Em seguida, juntamos a imagem e o nome  dentro de [] seguido do link do github em ()

- Por fim, os elementos são organizados em uma 'micro tabela', obtendo como resultado algo parecido com: 

Para inserir mais devs, basta adicionais mais colunas.

![amiguinhas](https://user-images.githubusercontent.com/46378210/80872475-8b603380-8c88-11ea-87d9-b98f21ad80e1.PNG)

### **Resolveu perrengues durante a aplicação? Documente!**

É inevitável que erros ocorram durante a execução do projeto, a gente se estressa, passa horas no _stackoverflow_ e em _issues_ procurando respostas. Apesar de conseguir resolver, pode ser que alguma hora eles voltem e não existe nada pior do que **esquecer de como resolver**. 

Não passe mais por isso! Quando tiver algum problema abra uma issue, apresente os erros e **mostre como resolver**, isso vai salvar a sua vida e a de outros devs em outros projetos. **É uma forma sensacional de contribuir pra comunidade.**

Claro, você pode deixar isso explicado no README.md também:  

```
### Resolvendo problemas

Veja alguns problemas que surgiram no desenvolvimento deste projeto e como os resolvi em [issues](https://github.com/Diana-ops/treina-dev-turma-3/issues)
```
![issues](https://user-images.githubusercontent.com/46378210/80872441-5b189500-8c88-11ea-8823-bd8f0bebf37e.PNG)

### **Ei, posso copiar o seu projeto?**

A sua aplicação pode ter algum tipo de licença, que da **direitos e restrições** ao que as pessoas podem fazer com ele é muito importante que você **deixe isso claro**. 

A licença mais utilizada é a MIT, que permite que qualquer pessoa possa usar, modificar e distribuir o seu projeto, mas te resguarda sob qualquer responsabilidade.   

Para inserir, acesse 

1. Insights > Community 
2. Clique em `add` para licence
3. Uma PR será aberta e ao aceita-la uma nova branch será criada
4. Agora, o simbolo de MIT estará no seu diretório

![licence](https://user-images.githubusercontent.com/46378210/80872429-4b00b580-8c88-11ea-9218-03eb3578cfad.PNG)

### **Fechando com chave de ouro**

Ufa, depois de ter mais esse trabalhão escrevendo a documentação podemos fazer uma lista de conteúdos (como se fosse um sumário) lá no começo do README.md que irá ajudar o visitante a ir direto ao tópico que ele quer.

```
### Tabela de Conteúdos
   * [Nome do tópico visivel](#nome-do-tópico)

### Nome do Tópico
```

:warning: Para referenciar o tópico substitua letras maiúsculas por minusculas
:warning: Caso o tópico tenha traços, ponto de interrogação e exclamação escreva como se não tivesse, pois **o markdown não consegue encontrar**. 
:warning: Caso o tópico esteja acompanhado de um emoji, escreva-o ignorando o simbolo ::

### **Deixe a preguiça de lado**

Não espere o projeto terminar para começar a documentação. Pelo contrário! Deixe isso como a primeira tarefa, assim você pode planejar e documentar ao mesmo tempo.  

Lembrando, não é obrigatório colocar todas essas informações e muito menos nessa ordem, tudo vai **depender do seu projeto** e os tópicos apesentados aqui são apenas sugestões. 

### **Presente**

Obrigada por ler até aqui, montei um [template](https://gist.github.com/reginadiana/e044fe93ed81aa04a10361cb841c0409) no gits com a estrutura de README mostrada neste artigo. Espero que gostem :heart:

![](https://media.giphy.com/media/kKo2x2QSWMNfW/giphy.gif)

 [Voltar para o inicio do artigo](#tópicos-deste-artigo)