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

Código Épico

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

Gabriel Nascimento
Escrito por Gabriel Nascimento em 29 de outubro de 2021

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?

o que é 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:

exemplo do que é markdown

Por que o README é tão importante?

cartão de visita do seu código

“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?

mostrar seu trabalho

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!

Como escrever um bom README?

como escrever um bom readme

Quando pesquisei sobre isso, 2 guias me ajudaram muito:

Primeiro, a página makeareadme.com. Sendo um manual simples, e com práticas essenciais, para fazer um README de qualidade.

Portanto, ótimo para quem está começando…

Porém, se você quer algo mais elaborado, esse guia da Rocketseat explica como usar recursos incríveis!

Conclusão

O README é uma parte importante do seu código…

Afinal, não adianta ser um programador fantástico, se ninguém entender o que você fez.

Além de ser um ótimo portfólio para mostrar o seu trabalho e ajudar você a ter destaque em uma vaga de emprego!

Espero que tenha gostado desse artigo! Não esqueça de comentar abaixo o que achou ou se ficou com alguma dúvida:

Hey,

o que você achou deste conteúdo? Conte nos comentários.

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *

One Reply to “O que é README e porque é tão importante?”