Criando Readme incríveis! 📖

Você sabe criar arquivos readme para seus repositórios de uma forma atrativa e informativa, ou apenas deixa o readme padrão do React (just a joke)?
Nesse post vamos ver alguns exemplos e dicas de como deixar nosso arquivo de readme super legal e organizado, então vamos pôr a mão na massa.md.

• Badges
• Logo
• Titulo e descrição
• Gif ou imagem demo
• Sessões
• Sobre
• Como utilizar
• Instalar
• Como rodar e como utilizar
• Demo
• Campos do Github
• Utilize todo o poder do Markdown
• Conclusão

Badges

Badges são super legais para adicionar no nosso arquivo, além de dar um overview super rápido e deixar o projeto bem bonito.
Algumas que eu gosto muito de utilizar são as de tecnologia, dizendo algum framework/lib que utilizei, status da pipeline, stars e licença.
Alguns exemplos legais:

Você pode criar suas próprias badges utilizando o shields.io ou pode encontrar várias prontas, inclusive nesse repositório aqui: https://github.com/Ileriayo/markdown-badges.

Logo

Criar uma logo ou utilizar algo pra representar é algo super legal e que dá um toque super bonito pra o repo, é uma dica bem opcional, mas que faz muita diferença.
Aqui também é legal implementar versões de imagem para cada tema (light ou dark) caso seu repositório esteja no Github, você pode fazer isso vendo este post
Uma dica pra quem não tem tanta afinidade com design é utilizar serviços de criação de logo online, como o Launchaco ou encontrar uma logo open source aqui: https://openlogos.org/.
{% github https://github.com/tuliocll/elixir-http-request %}

Titulo e descrição

Esse é super importante, lembre-se sempre de adicionar o título e a descrição do seu projeto de forma simples e bem direta.
Você pode criar o título e logo abaixo a descrição, ou criar uma sessão para a descrição depois do título.

Utilize as tags do markdown para isso:

# Meu projeto
Descrição do meu projeto...

Gif ou imagem demo

É super legal quando a gente entra em um repo e tem logo de cara uma prévia do que esperamos ver, adicionar uma imagem ou um vídeo para isso é uma dica super válida.
{% github tuliocll/summaryze-forem %}

Sessões

Eu gosto de dividir o projeto em várias sessões: sobre, como funciona, como instalar etc...

Sobre

Gosto de criar uma sessão de sobre e detalhar mais sobre o projeto, o que me motivou, como ele foi feito etc.

Como utilizar

É legal uma parte falando como utilizar o projeto (caso seja necessário).

Instalar

Uma sessão mostrando comando a comando como instalar o projeto também é super valido.

Como rodar e como utilizar

Sempre deixo os comandos de como rodar em cada ambiente (caso seja o caso), prontos para serem copiados e colados.

Demo

Caso seja possível, é sempre legal deixar um link de uma demo online, dessa forma, se for um projeto pessoal ou algum estudo que você fez, quem estiver vendo conseguirá ter a experiência de uso sem precisar fazer todo o processo de instalação.

Campos do Github

Preencha campos específicos do github, como: about e as tag.
Ajuda seu repositório ser encontrado facilmente e deixa mais organizado também.

Utilize todo o poder do Markdown

O Markdown nos oferece coisas incríveis, assim como no html conseguimos criar links, tabelas, títulos e várias outras coisas. Eu recomendo duas coisas aqui nesse ponto, a primeira é que você leia essa documentação sobre as tags do markdown e a segunda é um editor em markdown online com diversas dessas tags em forma de um editor de texto.

Bonus

Uma ferramenta online super legal e que conheci recentemente (depois de escrever esse post) foi o Readme.so. Você consegue criar readmes de forma mais visual e com uma padronização excelente!

Conclusão

Vou deixar aqui alguns repositórios meus que tem uns readme que eu gosto bastante e caso vocês queiram se inspirar.
Conhece algum repo que tem um readme muito legal? Comenta pra gente!