Como fazer um bom README
Guia Rocketseat para um README de qualidade
Se você não leu o post O que é README recomendo que leia, se já sabe da importância desse arquivo no projeto, pode continuar por aqui.
Vamos aprender como estruturar um bom README. No final vou deixar um template baseado no que vamos aprender e indicar referências interessantes que encontrei sobre o assunto.
Separei em duas categorias: opcional e obrigatório. Na descrição de cada item vou especificar em qual categoria ele se encaixa. Confere aí.
Estrutura do README
Essa é uma sugestão de estrutura, cada um pode fazer conforme a necessidade do projeto. Vamos agora cobrir cada um dos tópicos da estrutura e outros pontos adicionais.
✅ Logo ou Banner
Status: Opcional
Se seu projeto já tem uma logo adicione no README. Pode ser um banner também. Você pode criar uma logo ou banner usando o Canva.
A logo ou banner podem substituir o título, mas não a descrição do projeto, veja um exemplo. O bom de manter o título e descrição em texto é que ajuda no SEO do Github, o Google vai ajudar indexar melhor seu projeto nas primeiras páginas de pesquisas, além de dar um resumo sobre o seu projeto.
Oferta nunca antes vista de aniversário da RocketseatGaranta 5 anos de acesso pelo menor preço possível e mude sua carreira para sempre.
Título e Descrição
Status: Obrigatório
Título: Nome curto do projeto
Descrição: Uma breve descrição do objetivo do projeto.
# Nome do Projeto ou <h1 align="center">Nome do Projeto</h1>
Nome do Projeto
Com a descrição:
## Descrição do Projeto <p align="center">Escrever uma breve descrição</p>
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>
🔗 React
🚀 lib para construir interfaces do usuário com componentes reutilizáveis
✅ Badges
Status: Opcional
É uma questão de gosto pessoal e comunicação. As badges são úteis para indicar o status do projeto: você pode colocar a versão dele, link para licença, quantidade de issues, status da build, status dos testes. Vale muito a pena colocar.
As badges podem ficar no topo antes do título ou abaixo da descrição.
Use o site shields.io para gerar suas badges.
Você pode criar a sua própria badge:
Os ícones de várias logos de produtos e tecnologias você encontra aqui: simpleicons.org.
Podemos customizar partir da URL a abaixo:
https://img.shields.io/static/v1?label=<LABEL>&message=<MESSAGE>&color=<COLOR>&style=<STYLE>&logo=<LOGO>
Os parâmetros significam:
- LABEL: texto do campo esquerdo
- MESSAGE: texto do campo direto
- COLOR: cor do campo direito, pode usar RGB.
- STYLE: estilo do badge inteiro. Podemos ter: plastic, flat, for-the-badge, social ou flat-square. Teste cada uma delas.
- LOGO: logo do campo esquerdo
Como exemplo, vou escolher os seguintes parâmetros:
- LABEL: como Blog
- MESSAGE: como Rocketseat
- COLOR: 7159c1
- STYLE: como for-the-badge
- LOGO: como GHOST
Podemos colocar ele no README assim em HTML:
<img src="https://img.shields.io/static/v1?label=Blog&message=Rocketseat&color=7159c1&style=for-the-badge&logo=ghost"/>
ou ainda em Markdown:
Pronto. Veja como ficou o badge personalizado:
Legal que no site shields.io tem o input search / project URL que você cola o link do projeto do seu Github e ele sugere alguns badges.
Tem esse repositório com algumas badges prontas: Naereen/badges
✅ Tabela de Conteúdos
Status: Obrigatório
É ótimo colocar os índices de conteúdos, que é tabela onde a pessoa clica e vai para o tópico específico.
Exemplo com markdown:
Tabela de conteúdos
=================
<!--ts-->
* [Sobre](#Sobre)
* [Tabela de Conteudo](#tabela-de-conteudo)
* [Instalação](#instalacao)
* [Como usar](#como-usar)
* [Pre Requisitos](#pre-requisitos)
* [Local files](#local-files)
* [Remote files](#remote-files)
* [Multiple files](#multiple-files)
* [Combo](#combo)
* [Tests](#testes)
* [Tecnologias](#tecnologias)
<!--te-->https://github.com/ekalinin/github-markdown-toc#table-of-contentsResultado:
Tabela de conteúdos
Se o README tiver poucos tópicos pode fazer inline, com HTML:
<p align="center"><a href="#objetivo">Objetivo</a> •
<a href="#roadmap">Roadmap</a> •
<a href="#tecnologias">Tecnologias</a> •
<a href="#contribuicao">Contribuição</a> •
<a href="#licenc-a">Licença</a> •
<a href="#autor">Autor</a></p>https://github.com/animavita/animavitaResultado:
No README.md do Github você pode usar HTML o que ajuda muito. 👌
✅ Status do Projeto
Status: Obrigatório
Indica se o projeto está em desenvolvimento ou já foi concluído.
<h4 align="center"> 🚧 React Select 🚀 Em construção... 🚧 </h4>
Resultado:
🚧 React Select 🚀 Em construção... 🚧
Oferta nunca antes vista de aniversário da RocketseatGaranta 5 anos de acesso pelo menor preço possível e mude sua carreira para sempre.
✅ Features
Status: Opcional
Você pode listar as funcionalidades da aplicação.
É opcional, porém é muito importante colocar. Isso ajuda demais as pessoas entenderem o que já tem feito, se estiver em construção você vai checkando o que está pronto.
Exemplo:
### Features - [x] Cadastro de usuário - [x] Cadastro de cliente - [ ] Cadastro de produtos
No Github ou gist fica com essa aparência abaixo. Resultado:
✅ Demonstração da aplicação
Status: Opcional
Se for um projeto web e estiver hospedado em algum lugar, forneça o link. Se o deploy foi feito no Netlify tem um badge para isso.
Se for uma API backend pode customizar um badge com um ícone do heroku. Pode também colocar o arquivo do Insomnia para ficar mais rápido para o usuário testar a API — Fica muito bom.
Se a aplicação estiver em desenvolvimento, se for um app mobile ou website coloque os prints da tela ou um gif ilustrando a utilização.
Exemplos de como usar imagens e gifs no README:
animavita/animavitaTrigger life-saving alerts, register animals for adoption and find the closest pet friend to adopt :dog: - animavita/animavitaGitHubanimavita
tgmarinho/meetappFinal Challenge of Rocketseat Bootcamp | Meetapp Backend, Frontend and Mobile - tgmarinho/meetappGitHubtgmarinho
lukemorales/rocketshoes-react-nativeNetShoes Clone with React Native and Redux. Contribute to lukemorales/rocketshoes-react-native development by creating an account on GitHub.GitHublukemorales
A maneira mais segura de manter os arquivos é criar uma pasta screenshots, github, assets, resources ou nome que você quiser e deixar os arquivos nela. Se você usar um CDN de imagens ou gif pode funcionar mas corre o risco do quebrar o link algum dia.
Supondo que você tenha criado uma pasta assets no seu projeto e tem o arquivo banner.png, é assim que você pode adicionar a imagem:
<h1 align="center"><img alt="NextLevelWeek" title="#NextLevelWeek" src="./assets/banner.png" /></h1>
Resultado:
Exemplo de como adicionar um banner com markdown:
Nesse caso estou usando algo genérico, usando uma imagem minha do banner do meu perfil no Twitter.
Oferta nunca antes vista de aniversário da RocketseatGaranta 5 anos de acesso pelo menor preço possível e mude sua carreira para sempre.
Outra maneira:
* SignUp Mobile 
Eu prefiro usar as tags HTML porque permitem customizar melhor, centralizar e diminuir a imagem.
Se quiser arriscar com algum serviço de hospedagem tem essa opção: imgur.com, se for um gif pode usar esse aqui giphy.com.
✅ Pré-requisitos e como rodar a aplicação/testes
Status: Obrigatório
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.
Exemplo:
### Pré-requisitos Antes de começar, você vai precisar ter instalado em sua máquina as seguintes ferramentas: [Git](https://git-scm.com), [Node.js](https://nodejs.org/en/). Além disto é bom ter um editor para trabalhar com o código como [VSCode](https://code.visualstudio.com/) ### 🎲 Rodando o Back End (servidor) ```bash # 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> ```
✨ Resultado:
Pré-requisitos
Antes de começar, você vai precisar ter instalado em sua máquina as seguintes ferramentas:
Além disto é bom ter um editor para trabalhar com o código como VSCode
🎲 Rodando o Back End (servidor)
# 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>
✅ Tecnologias utilizadas
Status: Obrigatório para projetos de portfólio/estudos.
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/)
Resultado:
🛠 Tecnologias
As seguintes ferramentas foram usadas na construção do projeto:
✅ Contribuição
Status: Opcional
Se seu projeto começar a receber contribuições, uma maneira legal de reconhecer o trabalho dessas pessoas é adicionando na lista de contribuidores.
Com certeza eles contribuíram porque gostam do projeto, e vão amar ♥️ receber esse esse reconhecimento.
Segue um modelo bem legal:
Eles utilizaram um bot pra criar essa lista: https://allcontributors.org/docs/en/bot/overview
Mas se não usar algo complexo, pode fazer simples: Link para exemplo.
Oferta nunca antes vista de aniversário da RocketseatGaranta 5 anos de acesso pelo menor preço possível e mude sua carreira para sempre.
Resultado:
É bom colocar o arquivo CONTRIBUTING.md na raiz do projeto para os devs saberem os passos de como contribuir no projeto.
✅ Autor
Status: Obrigatório
Aqui entra seu jabá, interessante colocar seus contatos, redes sociais para as pessoas te encontrarem e começar um networking:
Resultado:
✅ Licença
Status: Obrigatório
A maioria dos devs utilizam a licença MIT que permite as pessoas baixarem o projeto e modificar e você não será responsabilizado por nada.
Muito simples escolher uma licença, o github te ajuda com isso te dando um template.
Geralmente você cria um arquivo LICENSE.
Exemplo:
MIT License Copyright (c) <2020> <Seu Nome> Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
E se quiser pode usar o Badge também:
- Crie usando esse link.
✅ Emojis
Status: Opcional
Vamos falar ainda sobre Emojis que estão bem na moda. Tem gente que não gosta, mas eles dão emoção ao texto e deixam o visual mais caprichado, porém não pode exagerar.
Fica legal colocar nos tópicos ou nas listas. Exemplo:
🏁 Tópicos
⚒️ Ferramentas:
Sites que dão dicas e inclusive um code/preview do README para seu projeto:
Conclusão
Escrever o README português ou inglês? Depende do objetivo do projeto, se for um portfólio e você está procurando emprego na gringa, tem que ser em inglês. Se for uma uma lib que pode ser usada por todo mundo, é interessante escrever em inglês, sua ferramenta vai ter mais alcance e relevância.
Se estiver começando no mundo da programação e não sabe inglês, faça em português mesmo, esse é o seu momento, mas estude inglês.
Dá para escrever em outros idiomas também, mas ai você pode pedir colaboração para isso, claro! Pode ter um README-en.md, ou seja internacionalizar o README e fornecer os links no README principal.
Se o projeto for algum portfólio para mostrar para alguma empresa aqui no Brasil pode ser em português mesmo. Depende do foco, momento e objetivo do projeto.
🎁 Template
Utilize esse template que preparamos para você construir o seu README. 💝
Para copiar a estrutura do README você tem que clicar no arquivo README.md e depois clicar na opção RAW, selecionar tudo, copiar e colar no seu editor preferido que suporte HTML e Markdown.
🔗 Links de README inspiradores:
➕ Mais sobre o assunto e outros aspectos interessantes:
- https://dev.to/reginadiana/como-escrever-um-readme-md-sensacional-no-github-4509#estrutura-do-readme
Posta aí nos comentários o seu README bonitão :)
Espero que tenha curtido! 💜
O aprendizado é contínuo e sempre haverá um próximo nível!
Como fazer um bom READMEgithub13 de Jul de 2020
Guia Rocketseat para um README de qualidade
Se você não leu o post O que é README recomendo que leia, se já sabe da importância desse arquivo no projeto, pode continuar por aqui.
Vamos aprender como estruturar um bom README. No final vou deixar um template baseado no que vamos aprender e indicar referências interessantes que encontrei sobre o assunto.
Separei em duas categorias: opcional e obrigatório. Na descrição de cada item vou especificar em qual categoria ele se encaixa. Confere aí.
Oferta nunca antes vista de aniversário da RocketseatGaranta 5 anos de acesso pelo menor preço possível e mude sua carreira para sempre.
Estrutura do README
Essa é uma sugestão de estrutura, cada um pode fazer conforme a necessidade do projeto. Vamos agora cobrir cada um dos tópicos da estrutura e outros pontos adicionais.
✅ Logo ou Banner
Status: Opcional
Se seu projeto já tem uma logo adicione no README. Pode ser um banner também. Você pode criar uma logo ou banner usando o Canva.
A logo ou banner podem substituir o título, mas não a descrição do projeto, veja um exemplo. O bom de manter o título e descrição em texto é que ajuda no SEO do Github, o Google vai ajudar indexar melhor seu projeto nas primeiras páginas de pesquisas, além de dar um resumo sobre o seu projeto.
Título e Descrição
Status: Obrigatório
Título: Nome curto do projeto
Descrição: Uma breve descrição do objetivo do projeto.
# Nome do Projeto ou <h1 align="center">Nome do Projeto</h1>
Nome do Projeto
Com a descrição:
## Descrição do Projeto <p align="center">Escrever uma breve descrição</p>
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>
🔗 React
🚀 lib para construir interfaces do usuário com componentes reutilizáveis
✅ Badges
Status: Opcional
É uma questão de gosto pessoal e comunicação. As badges são úteis para indicar o status do projeto: você pode colocar a versão dele, link para licença, quantidade de issues, status da build, status dos testes. Vale muito a pena colocar.
As badges podem ficar no topo antes do título ou abaixo da descrição.
Use o site shields.io para gerar suas badges.
Você pode criar a sua própria badge:
Os ícones de várias logos de produtos e tecnologias você encontra aqui: simpleicons.org.
Podemos customizar partir da URL a abaixo:
https://img.shields.io/static/v1?label=<LABEL>&message=<MESSAGE>&color=<COLOR>&style=<STYLE>&logo=<LOGO>
Os parâmetros significam:
- LABEL: texto do campo esquerdo
- MESSAGE: texto do campo direto
- COLOR: cor do campo direito, pode usar RGB.
- STYLE: estilo do badge inteiro. Podemos ter: plastic, flat, for-the-badge, social ou flat-square. Teste cada uma delas.
- LOGO: logo do campo esquerdo
Como exemplo, vou escolher os seguintes parâmetros:
- LABEL: como Blog
- MESSAGE: como Rocketseat
- COLOR: 7159c1
- STYLE: como for-the-badge
- LOGO: como GHOST
Podemos colocar ele no README assim em HTML:
<img src="https://img.shields.io/static/v1?label=Blog&message=Rocketseat&color=7159c1&style=for-the-badge&logo=ghost"/>
ou ainda em Markdown:
Pronto. Veja como ficou o badge personalizado:
Legal que no site shields.io tem o input search / project URL que você cola o link do projeto do seu Github e ele sugere alguns badges.
Tem esse repositório com algumas badges prontas: Naereen/badges
✅ Tabela de Conteúdos
Status: Obrigatório
É ótimo colocar os índices de conteúdos, que é tabela onde a pessoa clica e vai para o tópico específico.
Exemplo com markdown:
Tabela de conteúdos
=================
<!--ts-->
* [Sobre](#Sobre)
* [Tabela de Conteudo](#tabela-de-conteudo)
* [Instalação](#instalacao)
* [Como usar](#como-usar)
* [Pre Requisitos](#pre-requisitos)
* [Local files](#local-files)
* [Remote files](#remote-files)
* [Multiple files](#multiple-files)
* [Combo](#combo)
* [Tests](#testes)
* [Tecnologias](#tecnologias)
<!--te-->https://github.com/ekalinin/github-markdown-toc#table-of-contentsResultado:
Tabela de conteúdos
Se o README tiver poucos tópicos pode fazer inline,
<p align="center"><a href="#objetivo">Objetivo</a> •
<a href="#roadmap">Roadmap</a> •
<a href="#tecnologias">Tecnologias</a> •
<a href="#contribuicao">Contribuição</a> •
<a href="#licenc-a">Licença</a> •
<a href="#autor">Autor</a></p>Resultado:
No README.md do Github você pode usar HTML o que ajuda muito. 👌
✅ Status do Projeto
Status: Obrigatório
Indica se o projeto está em desenvolvimento ou já foi concluído.
<h4 align="center"> 🚧 React Select 🚀 Em construção... 🚧 </h4>
Resultado:
🚧 React Select 🚀 Em construção...
✅ Features
Status: Opcional
Você pode listar as funcionalidades da aplicação.
É opcional, porém é muito importante colocar. Isso ajuda demais as pessoas entenderem o que já tem feito, se estiver em construção você vai checkando o que está pronto.
Exemplo:
### Features - [x] Cadastro de usuário - [x] Cadastro de cliente - [ ] Cadastro de produtos
No Github ou gist fica com essa aparência abaixo. Resultado:
✅ Demonstração da aplicação
Status: Opcional
Se for um projeto web e estiver hospedado em algum lugar, forneça o link. Se o deploy foi feito no Netlify tem um badge para isso.
Se for uma API backend pode customizar um badge com um ícone do heroku. Pode também colocar o arquivo do Insomnia para ficar mais rápido para o usuário testar a API — Fica muito bom.
Se a aplicação estiver em desenvolvimento, se for um app mobile ou website coloque os prints da tela ou um gif ilustrando a utilização.
Exemplos de como usar imagens e gifs no README:
animavita/animavitaTrigger life-saving alerts, register animals for adoption and find the closest pet friend to adopt :dog: - animavita/animavitaGitHubanimavita
tgmarinho/meetappFinal Challenge of Rocketseat Bootcamp | Meetapp Backend, Frontend and Mobile - tgmarinho/meetappGitHubtgmarinho
lukemorales/rocketshoes-react-nativeNetShoes Clone with React Native and Redux. Contribute to lukemorales/rocketshoes-react-native development by creating an account on GitHub.GitHublukemorales
A maneira mais segura de manter os arquivos é criar uma pasta screenshots, github, assets, resources ou nome que você quiser e deixar os arquivos nela. Se você usar um CDN de imagens ou gif pode funcionar mas corre o risco do quebrar o link algum dia.
Supondo que você tenha criado uma pasta assets no seu projeto e tem o arquivo banner.png, é assim que você pode adicionar a imagem:
<h1 align="center"><img alt="NextLevelWeek" title="#NextLevelWeek" src="./assets/banner.png" /></h1>
Resultado:
Exemplo de como adicionar um banner com markdown:
Nesse caso estou usando algo genérico, usando uma imagem minha do banner do meu perfil no Twitter.
Oferta nunca antes vista de aniversário da RocketseatGaranta 5 anos de acesso pelo menor preço possível e mude sua carreira para sempre.
Outra maneira:
* SignUp Mobile 
Eu prefiro usar as tags HTML porque permitem customizar melhor, centralizar e diminuir a imagem.
Se quiser arriscar com algum serviço de hospedagem tem essa opção: imgur.com, se for um gif pode usar esse aqui giphy.com.
✅ Pré-requisitos e como rodar a aplicação/testes
Status: Obrigatório
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.
Exemplo:
### Pré-requisitos Antes de começar, você vai precisar ter instalado em sua máquina as seguintes ferramentas: [Git](https://git-scm.com), [Node.js](https://nodejs.org/en/). Além disto é bom ter um editor para trabalhar com o código como [VSCode](https://code.visualstudio.com/) ### 🎲 Rodando o Back End (servidor) ```bash # 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> ```
✨ Resultado:
Pré-requisitos
Antes de começar, você vai precisar ter instalado em sua máquina as seguintes ferramentas:
Além disto é bom ter um editor para trabalhar com o código como VSCode
🎲 Rodando o Back End (servidor)
# 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>
✅ Tecnologias utilizadas
Status: Obrigatório para projetos de portfólio/estudos.
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/)
Resultado:
🛠 Tecnologias
As seguintes ferramentas foram usadas na construção do projeto:
✅ Contribuição
Status: Opcional
Se seu projeto começar a receber contribuições, uma maneira legal de reconhecer o trabalho dessas pessoas é adicionando na lista de contribuidores.
Com certeza eles contribuíram porque gostam do projeto, e vão amar ♥️ receber esse esse reconhecimento.
Segue um modelo bem legal:
Eles utilizaram um bot pra criar essa lista: https://allcontributors.org/docs/en/bot/overview
Mas se não usar algo complexo, pode fazer simples: Link para exemplo.
Oferta nunca antes vista de aniversário da RocketseatGaranta 5 anos de acesso pelo menor preço possível e mude sua carreira para sempre.
Resultado:
É bom colocar o arquivo CONTRIBUTING.md na raiz do projeto para os devs saberem os passos de como contribuir no projeto.
✅ Autor
Status: Obrigatório
Aqui entra seu jabá, interessante colocar seus contatos, redes sociais para as pessoas te encontrarem e começar um networking:
Resultado:
✅ Licença
Status: Obrigatório
A maioria dos devs utilizam a licença MIT que permite as pessoas baixarem o projeto e modificar e você não será responsabilizado por nada.
Muito simples escolher uma licença, o github te ajuda com isso te dando um template.
Geralmente você cria um arquivo LICENSE.
Exemplo:
MIT License Copyright (c) <2020> <Seu Nome> Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
E se quiser pode usar o Badge também:
- Crie usando esse link.
✅ Emojis
Status: Opcional
Vamos falar ainda sobre Emojis que estão bem na moda. Tem gente que não gosta, mas eles dão emoção ao texto e deixam o visual mais caprichado, porém não pode exagerar.
Fica legal colocar nos tópicos ou nas listas. Exemplo:
🏁 Tópicos
⚒️ Ferramentas:
Sites que dão dicas e inclusive um code/preview do README para seu projeto:
Conclusão
Escrever o README português ou inglês? Depende do objetivo do projeto, se for um portfólio e você está procurando emprego na gringa, tem que ser em inglês. Se for uma uma lib que pode ser usada por todo mundo, é interessante escrever em inglês, sua ferramenta vai ter mais alcance e relevância.
Se estiver começando no mundo da programação e não sabe inglês, faça em português mesmo, esse é o seu momento, mas estude inglês.
Dá para escrever em outros idiomas também, mas ai você pode pedir colaboração para isso, claro! Pode ter um README-en.md, ou seja internacionalizar o README e fornecer os links no README principal.
Se o projeto for algum portfólio para mostrar para alguma empresa aqui no Brasil pode ser em português mesmo. Depende do foco, momento e objetivo do projeto.
🎁 Template
Utilize esse template que preparamos para você construir o seu README. 💝
Para copiar a estrutura do README você tem que clicar no arquivo README.md e depois clicar na opção RAW, selecionar tudo, copiar e colar no seu editor preferido que suporte HTML e Markdown.
🔗 Links de README inspiradores:
➕ Mais sobre o assunto e outros aspectos interessantes:
- https://dev.to/reginadiana/como-escrever-um-readme-md-sensacional-no-github-4509#estrutura-do-readme
Posta aí nos comentários o seu README bonitão :)
Espero que tenha curtido! 💜
O aprendizado é contínuo e sempre haverá um próximo nível!
