Como criar um bom README.md?
- #GitHub
O que é um arquivo README?
README é o primeiro arquivo ao qual somos introduzidos quando estamos iniciando um novo projeto. Ele é um conjunto de informações úteis sobre o projeto, e de certa forma, um manual.
A terminação .md indica que ele é um arquivo escrito em markdown. E o que é markdown? É uma linguagem de marcação em que é possível adicionar elementos de formatação em documentos de texto. As vantagens de se utilizar markdown são:
- Pode ser utilizado para tudo. Como em criação de websites, documentos, anotações, apresentações e mensagens de e-mail.
- Portabilidade. Arquivos que contem markdown podem ser abertas em qualquer tipo de editor de texto.
- Resistentes ao tempo. Mesmo que sua aplicação pare de funcionar depois de um tempo, você ainda será capaz de ler seus arquivos em markdown.
Deixarei aqui um site com alguns comandos em markdown para que você já seja capaz de testar as funcionalidades dentro do seu arquivo. 😉
Site: https://docs.pipz.com/central-de-ajuda/learning-center/guia-basico-de-markdown#open
Qual a vantagem em escrever um bom README?
Um bom README serve para outras pessoas entenderam o que seu código possui. A maioria dos projetos no github servem como um portfolio. Quando estamos no inicio de nossas carreias e sem experiência comercial suficiente, uma apresentação de nossas conquistas em forma de repositório é a melhor forma de chamar a atenção de recrutadores. Com ele, mesmo um recrutador não-técnico será capaz de reconhecer as tecnologias que usamos e verificar se estamos atendendo os critérios que ele procura.
Escrevendo seu README - um breve tutorial 💻
O conteúdo do README deve seguir uma estrutura que primeiro introduz o projeto, então explica como instalar e fazer uso do mesmo. E finalmente, explicar como participar do projeto como um contribuidor para os outros usuários.
Tenha certeza de sempre incluir os seguintes elementos:
- Títulos e subtítulos
- Introdução
- Tecnologias
- E como rodar o projeto
Considere também outros elementos como:
- Índice de conteúdo
- Ilustrações
- Escopo de funcionalidades
- Exemplo de usos
- Status do projeto
- Referências
- Logo ou Banner
✔ TITULOS E SUBTITULOS
Um titulo deve explicar claramente do que se trata e geralmente é o nome do projeto.
# Nome do Projeto
ou
<h1 align="center">Nome do Projeto</h1>
Também escrever uma breve descrição:
<h1 align="center">
<a href="<https://pt-br.reactjs.org/>">🔗 React</a>
</h1>
<p align="center">lib para construir interfaces do usuário com componentes reutilizáveis</p>
✔ INTRODUÇÃO
Serve como um sumário. Não deve ser muito longo, nós devemos descrever de uma maneira interessante qual é o objetivo do nosso projeto e qual problema aquela aplicação soluciona. Duas ou três sentenças é o suficiente no caso de um projeto menor. E se for em um projeto de treino, mencione as motivações da sua iniciativa. Por que você quis criar esse projeto? Para aprender uma tecnologia especifica? Foi um projeto de hackathon ou bootcamp? É com certeza muito importante adicionar as suas razões.
✔ TECNOLOGIAS
Listar as tecnologias e colocar os links para o seus respectivos sites é um plus no README.
### 🛠 Tecnologias
As seguintes ferramentas foram usadas na construção do projeto:
- [Expo](<https://expo.io/>)
- [Node.js](<https://nodejs.org/en/>)
- [React](<https://pt-br.reactjs.org/>)
- [React Native](<https://reactnative.dev/>)
- [TypeScript](<https://www.typescriptlang.org/>)
✔ COMO RODAR A APLICAÇÃO
Como rodar o projeto? O sistema tem os requerimentos mínimos de hardware? Se o projeto for uma lib, você tem que mostrar os passos de como instalar e usar a lib, se for um projeto backend | web | mobile | desktop descreva os passos de como fazer para rodar na máquina. Se tiver testes é bom descrever como rodar os testes.
# Clone este repositório
$ git clone <https://github.com/tgmarinho/nlw1>
# Acesse a pasta do projeto no terminal/cmd
$ cd nlw1
# Vá para a pasta server
$ cd server
# Instale as dependências
$ npm install
# Execute a aplicação em modo de desenvolvimento
$ npm run dev:server
# O servidor inciará na porta:3333 - acesse <http://localhost:3333>
✔ CONTRIBUIÇÃO
É bom colocar o arquivo CONTRIBUTING.md na raiz do projeto para os devs saberem os passos de como contribuir no projeto.
➕ BÔNUS
Links de README inspiradores:
- https://github.com/ant-design/ant-design
- https://github.com/animavita/animavita
- https://github.com/iterative/cml
- https://github.com/danileao/rocketmusic
- https://github.com/gatsbyjs/gatsby
- https://github.com/x0n4d0/ecoleta
- https://github.com/tgmarinho/meetapp
- https://github.com/steniowagner/mindCast
- https://github.com/fastify/fastify
- https://github.com/invertase/react-native-firebase
- https://github.com/JedWatson/react-select
- https://github.com/fkhadra/react-toastify
- https://github.com/facebook/react-native
- https://github.com/tgmarinho/Ecoleta
- https://github.com/othneildrew/Best-README-Template
----------------------------------------------------------------------------
