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: Linkedin Badge

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 😁

[![Linkedin Badge](https://img.shields.io/badge/-Leonardo-blue?style=rounded&logo=Linkedin&logoColor=white&link=https://www.linkedin.com/in/leonardoluize/)](https://www.linkedin.com/in/leonardoluize/) 
[![Gmail Badge](https://img.shields.io/badge/-leonardo.luize2@gmail.com-c14438?style=rounded&logo=Gmail&logoColor=white&link=mailto:leonardo.luize2@gmail.com)](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!

Boaa, acho que é uma ótima dica mesmo, vou ver de adicionar!

obrigado por ajudar o newbie

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!

Obrigado, muito grato por poder ajudar :)