LEIA-ME ou te devoro: Como escrever um bom README

Que título dramático, você deve está pensando… Mas eu não resisti e tiver que usar essa frase.
Até porque READMEs são feitos para, como o nome diz, serem lidos, e se você tentar contribuir ou usar um projeto open source sem ler esse documento, você pode ser, metaforicamente, devorada por dúvidas.

Hoje escolhi falar sobre READ.ME porque essa é a página inicial de qualquer projeto open source, desde de um framework famoso como o React,js, até daquela calculadora que você fez pra praticar seus conhecimentos de programação.

O que é um README e porque eu deveria me importar?

Mas o que é o README? O nome, traduzido para o português fica como LEIAME, o que já dá a dica de que é um documento que deve ser lido. Mas, por que?

O README é um arquivo em markdown (.md) que é considerado o manual de instruções do seu projeto. Ele tem que conter informações úteis para que outras pessoas possam entender, contribuir e usar seu projeto, apenas lendo esse arquivo.

Você deveria se importar porque esse é o primeiro arquivo que as pessoas vão ler no seu projeto! Ter um bom README também ajuda seu projeto a ter destaque, já que outros projetos muitas vezes não tem um bom README.

Como criar o arquivo README

Direto pelo GitHub

Primeiro vamos as tecnicalidades. Tem várias formas de se criar um README.

A primeira é quando você criar seu novo projeto no GitHub, na página de criação você vai encontrar o texto Inicialize esse repositório com, e Add um arquivo README é a primeira opção. Você pode clicar na caixinha aqui e seu projeto já vai ser criado com um README:

Isso vai criar no root do seu repositório o arquivo README.md e o conteúdo desse arquivo é o que aparece na página inicial do repo.

O README criado aqui é bem básico, mas neste artigo vou ensinar como deixar ele mais completo.

Criar manualmente

Se você já tem um projeto criado, ou quer criar o README manualmente, tudo que você tem que fazer é criar um arquivo com o nome README.md no root do projeto, por onde você preferir (terminal, IDE, pelo GitHub mesmo).

Na imagem abaixo, você pode ver o exemplo de um REAME sendo criado dentro da pasta leiame pelo terminal do Git

Agora que já temos nosso arquivo criado, vamos editá-lo com os itens necessários?

Editando seu README

O arquivo README pode conter diversas informações sobre o seu projeto e muitos desses itens vão ser opcionais, mas um bom README deve ter, no mínimo, o título do projeto e uma boa descrição, como instalar e rodar o projeto, como usar, como contribuir e a licença dele.

Vamos falar sobre cada um desses itens.

Título e Descrição

O título tem que ser algo curto, mas o mais descritivo possível, para ajudar as pessoas a entenderem qual o objetivo principal do projeto.

Já a descrição complementa o título: O que o projeto faz e para que serve? Quais as tecnologias usadas neste projeto? Você pode adicionar também desafios que você teve criando projetos e features que espera adicionar no futuro.

Ouso dizer que a descrição é a parte mais importante de qualquer README, então dedique um carinho especial para essa sessão <3

Como Instalar e Rodar o projeto

Esse item não se aplica a todos os projetos, mas seu projeto é algo que as pessoas têm que instalar e rodar localmente, isso é algo super importante.

Aqui você deve incluir um passo-a-passo detalhado de como instalar o projeto e tudo que é necessário para fazer o ambiente de desenvolvimento rodar sem problemas.

Como Usar o projeto

Escreva aqui instruções de como usar seu projeto e adicione exemplos de como ele já foi usado (uma ótima dica é pedir para quem já usa o projeto contribuir nessa sessão).

Aqui é legal adicionar visuais, como prints do projeto funcionando e qualquer outra coisa que você considere interessante e relevante.

Como Contribuir

Projetos Open Source geralmente estão sempre aceitando contribuições (esse é, afinal, o apelo principal de Open Source), então é bom ter um guia de contribuições. Se uma pessoa quiser contribuir, o que ela deve fazer?

Apenas dar um Fork e criar uma PR ou ela precisa criar uma issue primeiro?

Temos um guia de diretrizes de contribuição, caso você queira inspiração.

Licença

Quando você criar um novo repositório no GitHub, vão te perguntar que licença você quer usar.

A licença diz às pessoas o que elas podem e o que elas não podem fazer com o seu código, como alterar, usar e distribuir.

Existem várias e eu geralmente vejo projetos pequenos usando a MIT. Mas se você tem grandes ambições para seu projeto, recomendo pesquisar mais sobre licenças para não ter problemas futuros

Itens opcionais

Os itens acima são os que eu considero essenciais para um README bem feito, mas você sempre pode melhorar.

Como itens opcionais temos:

• Uma tabela de conteúdo, caso seu README fique muito extenso, é um bom item para facilitar a leitura.

• Créditos, (caso você teve ajuda ou se inspirou em algum outro projeto ou pessoa, é sempre legal dar crédito a quem merece.

• Badges são um ótimo visual, e existem todos os tipos de badge. Você só tem que ir no https://shields.io/, copiar o código da badge deseja e adicioná-la ao seu repo. Você pode usar uma badge para demonstrar qual a licença do projeto, por exemplo:

DESAFIO: Vamos criar um README?

Isso é tudo que eu tinha para vocês hoje, e quero deixar aqui um desafio: Vá em algum dos projetos que você já tem no GitHub e crie um README bonitinho.

Depois vem aqui e comenta com o Link do repositório para eu ver!

Você também pode compartilhar nas redes sociais se preferir, mas por favor mencione esse artigo <3

Obrigada por ler até aqui,

Pachi 🥑