Conheça o Rocketseat Para Empresas
Oferecemos soluções personalizadas para empresas de todos os portes.
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:
Conheça o Rocketseat Para Empresas
Oferecemos soluções personalizadas para empresas de todos os portes.
NewsletterReceba conteúdos inéditos e novidades gratuitamente
