loading...
Cover image for Como escrever um README.md sensacional no Github

Como escrever um README.md sensacional no Github

reginadiana profile image Diana Regina Updated on ・10 min read

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

Tópicos deste artigo

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 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, 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

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

Badges servem para certificar ou indicar algo do teu projeto como status, licença, linguagens, testes, etc. Para saber mais acessem a documentação.

Para utilizados podemos entrar o site shields.oi. 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

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

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

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. 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

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

Deploy da aplicação? Oba

Se for possível subir a aplicação com Netlify 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

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

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

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

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

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

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

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

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

⚠️ Para referenciar o tópico substitua letras maiúsculas por minusculas
⚠️ 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.
⚠️ 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 no gits com a estrutura de README mostrada neste artigo. Espero que gostem ❤️

Voltar para o inicio do artigo

Posted on by:

reginadiana profile

Diana Regina

@reginadiana

Apaixonada por Web Design, participou do Bootcamp de React da WoMakersCode e Treina Dev da Campus Code.

Discussion

markdown guide
 

Menina, parabéns! Material completíssimo, didático e muito útil. Grato pela contribuição. Veja o meu resultado, conforme suas dicas: github.com/paulinhovba/DGP-Manager...

 

Muito bacana Paulo!! Gostei do desenvolvimento do README e achei o projeto interessante tambem!! Aproveito para elogiar o teu site pessoal, esta incrivel, muito bom!!

 

Minha cara, desculpe o "flood" de replyes! Ao postar, recebi mensagem de erro e tentei algumas vezes e todas acabaram entrando. Já deletei os outros posts.

Iniciativas como a sua enriquecem muito a experiência humana. Compartilhar é crescer.

Agradeço pelo elogio, foi feito com muito amor!

Caso queira contribuir, o projeto será disponibilizado no git ainda hoje. Sinta-se livre para utilizar como lhe convier.

Se precisar de algo, estou sempre às ordens.

Um abraço!

hahaha deve ser bug no site, aconteceu a mesma coisa comigo quando fui te responder. Aliás, me inspirei no teu portfólio para construir o meu: dianaregina.netlify.app/

Diana, bom dia! Adorei seu novo site. Ficou muito bom mesmo. Parabéns!

 

Muito legal esse post me ajudou muito vlw Diana ta de parabéns!

 

Óptima explicação!
Devias fazer em inglês também 😉

 

Obrigada, é uma boa ideia :)

 
 

O melhor post que já encontrei sobre o assunto. Parabéns Diana!
Obrigado por compartilhar 📝 🚀

 

Muito obrigada, fico muito feliz :)

 

Muito massa. Usei bastante essas dicas no meu projetinho

 

Adorei seu artigo, parabéns e já estou usando pra editar o meu aqui. Muito bom menina, parabéns mesmo!

 
 
 

Excelente artigo. Tem está ferramenta que ajuda a criar uma estrutura inicial bem interessante de readme

 

Umas das coisas mais lindas que já li

 
 
 

Olá,gostaria de saber como que faz pra deixar em ''micro tabela'' nos desenvolvedores,fiz desse jeito,porém ficou um em baixo do outro

 

Olá Rafael, a base é fazer uma tabela:

Código:

|dev 1 |dev 2 |dev 3 |dev 4 |
| :---: | :---: | :---: | :---: | 

Resultado:

dev 1 dev 2 dev 3 dev 4

Dentro de cada dev/coluna inserimos uma imagem <img/>, quebra de elementos <br/> e texto <sub><sub/> dentro de um link [](). Dentro dos colchetes colocamos os elementos visiveis e nos parentes o link para o github

Código:

|[<img src="" width="largura da imagem"/><br/><sub>Nome do Dev</sub>]() | [<img src="" width="largura da imagem"/><br/><sub>Outro nome do Dev</sub>]()|
| :---: | :---: | 

Resultado:

Exemplo para 2 colunas:

Código:

[<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) | [<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) | 
| :---: | :---: |

Resultado:

Exemplo para 4 colunas:

Código:

[<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) | [<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) | [<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) | [<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)
| :---: | :---: | :---: | :---: | 

Resultado:

 

Muito bom material. Parabéns !