Primeiros passos para o README.md do seu projeto
Neste post gostaria de compartilhar algumas dicas que me ajudaram a estruturar meus primeiros README.md, quando comecei a organizar meus repositórios, também gostaria de pedir para que todos que tiverem mais dicas para agregar deixem nos comentários. :)
Dicas
Estrutura
Um ponto importante do readme é que ele siga uma lógica e que comunique o que é o seu projeto, como ele funciona, como o leitor pode rodar e quem contribuiu para o projeto.
Você pode seguir a lógica que melhor se encaixa para o seu projeto, eu particularmente gosto de seguir a seguinte estrutura:
- Logo
- Subtítulo
- Status
- Sobre
- Como rodar?
- Tecnologias que utilizei
- Contribuidores
Logo, Subtítulo e Status
No começo eu gosto de colocar uma logo centralizada com um subtítulo que expresse para que serve esse repositório e na sequencia o status do projeto, se ele está em andamento ou finalizado.
Ex:
<h1 align="center">
<img src="./public/images/logo.svg">
</h1>
<p align="center">Site de notícias sobre React feito no curso ignite</p>
<h4 align="center">
- Status: ✅ -
</h4>
Sobre
Aqui é interessante detalhar mais a ideia do repositório, comentando para que ele foi criado.
Ex:
### ☑️ Sobre
---
<p>
Seguindo as aulas do curso, desenvolvi este website que tem como foco mostrar notícias sobre React, a ideia principal é que para ver as notícias você pague uma assinatura mensal e caso o usuário não tenha a assinatura o site mostre apenas um preview da notícia.
</p>
Como rodar?
Um detalhe muito importante é dar as instruções de como o leitor pode rodar o projeto, detalhando os comandos e as dependências do projeto.
Ex:
### 🔌 Como rodar o projeto | Local
---
Caso queira rodar o projeto local, você deve rodar os seguintes comandos:
# Instale as dependências
$ npm install
# Execute o projeto em desenvolvimento
$ npm run dev
# Depois de iniciar o projeto em desenvolvimento, basta acessar http://localhost:3000/
Tecnologias
Aqui é simplesmente listar as tecnologias utilizadas com os links para os sites oficiais.
### 🔋 Tecnologias
---
- [React](https://pt-br.reactjs.org/)
- [NextJs](https://nextjs.org/)
- [FaunaDb](https://fauna.com/)
- [Stripe](https://stripe.com)
- [Prismic](https://prismic.io/)
- [TypeScript](https://www.typescriptlang.org/)
Contribuidores
Para finalizar gosto de deixar os contribuidores do projeto com links para linkeIn, email, codespace e entre outros. Para os links eu utilizo o img shields, dai o link fica um pouco mais estiloso 😎.
Img Shield:
Ex:
### 🎲 Feito por
---
<a href="https://github.com/LeonardoLuize">
<img src="https://avatars.githubusercontent.com/u/74014082?v=4" width="100px;"/>
<br />
<sub><b>Leonardo Luize</b></sub></a> <a href="https://github.com/LeonardoLuize" >💻</a>
Feito por Leonardo Luize 😁
[](https://www.linkedin.com/in/leonardoluize/)
[](mailto:leonardo.luize2@gmail.com)
Caso queira visualizar um exemplo da estrutura do readme que costumo usar, segue o link de um dos meus repos.
Considerações finais
Espero que essas dicas ajudem você a estruturar seu readme, outra referência é o blog da rocketseat.
Muito legal o post, parabéns! Além do que você sugere, acho que vale mencionar a licença (MIT, GPL, etc.) e as versões mínimas dos softwares necessários. Valeu!
Sou envolvido com diversos projetos open source (como mantenedor e contribuidor, o meu profile no github consegue falar muito melhor sobre minhas contribuições).
Toda vez que tenho uma ideia de fazer um novo projeto tenho habito de criar um repositório (no meu caso a grande maioria aberto) e escrever o README explicando qual problema esse projeto resolve ou quer resolver.
Tudo que coloco no readme é para justificar ao meu "eu do futuro" porque esta investindo tempo no projeto.
Nessa resposta falei um pouco mais sobre isso.
Que legal cara! 👏
Faz um tempo que estava tentando achar informações desse tipo sobre o readme. Obrigado por compartilhar!