O que é README e porque é tão importante

github 7 de Jul de 2020

O assunto aqui vai ser sobre o famoso README: vamos descobrir, na prática, o que é o Markdown e também esclarecer o motivo desse arquivo ser tão importante no projeto, e quais as vantagens de ter um bom README. No final vamos disponibilizar alguns links para te inspirar a escrever.

📝 O que é o README?

README.md é um arquivo com extensão .md (Markdown). Contém informações necessárias para entender o objetivo do projeto. README é uma palavra em inglês que traduzida fica LEIAME.

Você já deve ter baixado algum software que tinha um arquivo LEIAME.txt com algumas instruções de como usar.

Podemos considerar o README como um cartão de visita do seu projeto no Github ou em outras plataformas de repositórios remotos de código: Gitlab, Bitbucket, Azure Repos.

⌨️ O que é Markdown?

O Markdown é uma ferramenta de conversão de texto em HTML. Você escreve usando texto simples de fácil leitura e fácil escrita e depois é transformado em um HTML válido.

Markdown foi criado por John Gruber e Aaron Swartz e seu código fonte foi escrito em Perl. O site oficial é esse aqui.

Exemplos básico de Markdown:

## Isso é equivalente ao h2 do html, usado para título
Essa é uma maneira simples de deixar o texto **negrito** e palavras *itálicas* com Markdown.
Como é fácil fazer um link para um site: [link p/ Blog da Rocketseat!](https://blog.rocketseat.com.br/)

### Lista de todo:
- Estudar Node
- Estudar React 
- Estudar React Native

### Prioridades nos estudos
1. Estudar
2. Praticar
3. Revisar

> Eu sou um bloco de citação (blockquotes)


| Tabelas  |      São      |  Legais |
|----------|:-------------:|------:|
| col 1 is |  left-aligned | $1600 |
| col 2 is |    centered   |   $12 |
| col 3 is | right-aligned |    $1 |

✨ Resultado:

Isso é equivalente ao h2 do html, usado para título

Essa é uma maneira simples de deixar o texto negrito e palavras itálicas com Markdown.

Como é fácil fazer um link para um site: link para o Blog da Rocketseat!

Lista de todo:

Estudar Node
Estudar React
Estudar React Native

Prioridades nos estudos

Estudar
Praticar
Revisar

Eu sou um bloco de citação (blockquotes)

Tabelas	São	Legais
col 1 is	left-aligned	$1600
col 2 is	centered	$12
col 3 is	right-aligned	$1

😎 Por que o README é tão importante?

Os projetos que se destacam no Github, além daqueles que resolvem o problema da comunidade, também são aqueles bem documentados em um bom README.

Como já disse acima, o README é o cartão de visita do seu código!

Com um arquivo bem descrito — às vezes com imagens, vídeos ou gifs — o projeto tem mais relevância e deixa as pessoas mais aguçadas e curiosas para ler o código, instalar a lib e utilizar o seu projeto.

🎯 Qual a vantagem de escrever um README?

Os recrutadores também estão de olho nisso. Dependendo da cultura da empresa, eles dão muito valor para quem utiliza o Github, ainda mais se open source for um forte da empresa.

Como a maioria deles não tem conhecimento técnico, ao entrarem em seu repositório e lerem o seu README, vão entender o que foi feito ter uma ideia da complexidade das tecnologias envolvidas.

Isso é um grande portfólio e uma maneira de destacar o seu trabalho. Tem empresas que não pedem CV (currículo), elas querem ver o que você sabe na prática. A melhor forma é fazer um projeto de teste com eles ou apresentar algo que você já fez.

✍️ Como escrever um README?

O site makeareadme te ajuda com isso. No começo do site ele te dá algumas dicas e depois abaixo tem um template para você escrever e também ver o preview de como está ficando.

Acesse: https://www.makeareadme.com/

Se você conhece o básico do NPX, pode utilizar essa ferramenta.

npx readme-md-generator

Rodando esse comando na máquina, ele vai te fazer algumas perguntas e conforme você vai respondendo ela vai criando o conteúdo do README para você.

https://user-images.githubusercontent.com/9840435/60266022-72a82400-98e7-11e9-9958-f9004c2f97e1.gif

O gerador de README é bem legal, mas talvez você precise fazer alguns ajustes para melhorar. Seja objetivo ao descrever os caminhos e as decisões tomadas. Evite verbosidade no texto e seja conciso ao apresentar o projeto, como se estivesse apresentando um pitch dentro de um Hackathon ou numa reunião.

Temos um post que mostra na prática como criar um bom README.

👀 Conclusão

Quem já fez os desafios do bootcamp da Rocketseat nas últimas turmas devem ter notado uma evolução, onde os desafios são bem descritos, com imagens e com testes. Tudo feito em README.

Imagine que você fez um projeto há um ano, você provavelmente não vai lembrar como executá-lo de cabeça, certo? Se você tiver o README, tudo vai ficar fresquinho na memória e vais poder dar continuidade no projeto bem rápido.

Tudo isso além de poder te ajudar a ter destaque e conseguir uma vaga de emprego!