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:[email protected])
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.