O que é README e porque é tão importante?

Os projetos que se destacam, além de resolverem algum problema da comunidade, também são aqueles que possuem um bom README.

Afinal, ele aumenta a relevância do seu trabalho, além de chamar a atenção das pessoas para lerem seu código e usarem seu programa.

Então continue lendo esse artigo para descobrir o que é o README e como ele será útil para você:

O que é o README?

README.md é um arquivo usado para descrever seu projeto, como por exemplo:

Escrever um pequeno resumo;
Listar suas principais características;
Explicar como se executa o código;
Ou qualquer informação que você considere útil.

Portanto, podemos considerar o README como um cartão de visita do seu projeto.

Principalmente em plataformas de repositório de código, como o Github ou Gitlab.

Mas o que significa a extensão .md (Markdown)?

O que é Markdown?

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

Exemplo básico de Markdown:

## Isso é equivalente a um título h2 do html

Essa é uma maneira simples de deixar o texto **negrito** e palavras *itálicas* com Markdown.
Também é fácil fazer um link para um site: [link para o Blog Warcontent!](https://warcontent.com)

### Lista de tópicos:

- Tópico 1
- Tópico 2
- Tópico 3

### Lista numerada:

1. Primeiro item
2. Segundo item
3. Terceiro item

Resultado:

Por que o README é tão importante?

“Faça um README, porque ninguém pode ler sua mente (ainda…)” — makeareadme.com

De nada adianta ter um ótimo projeto (e super útil), se as pessoas não perceberem o potencial de sua criação.

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

Então um arquivo bem descrito — às vezes com imagens, vídeos ou gifs — chama mais atenção e deixa as pessoas mais curiosas para ler, instalar e utilizar o seu projeto.

Quais as vantagens de escrever um README?

Separei as vantagens do README em 3 categorias:

1. Projeto compartilhado

Se você quiser compartilhar o seu repositório para outras pessoas terem acesso ao seu código, é bom essa pessoa conseguir:

Entender do que se trata o seu projeto;
E ter instruções minimas de como usar.

Caso contrario, ela pode desistir antes mesmo de baixar os arquivos…

2. Projeto pessoal

Imagine que você fez um projeto há 1 ano…

Muita coisa foi esquecida e você vai precisar ler o código para saber como dar os primeiro passos.

Ou essa parte pode estar bem documentada em um bom README… Assim você evita muita dor de cabeça.

3. Portfólio

Muitos recrutadores olham os seus projetos no github para conhecer seu trabalho e saber do que você é capaz.

Alguns nem pedem seu currículo, apenas querem ver o que você sabe na prática. (às vezes em um projeto de teste ou apresentar algo que você já fez)

Porém a maioria deles não tem conhecimento técnico…

Apesar disso, ao entrarem no seu repositório e lerem o seu README, conseguem entender o que foi feito e ter uma ideia da complexidade envolvida.

Assim seu perfil no Github se torna um grande portfólio vivo!