Artigo original: How to Write a Good README File for Your GitHub Project

Quando me apresentaram o GitHub, eu não tinha ideia do que era ou do que podia fazer. Cá entre nós, eu criei uma conta porque me disseram que todo desenvolvedor deveria ter uma para poder colocar seu código.

Na maior parte do meu tempo de iniciante, eu não fiz nada com minha conta. Depois, em função da minha paixão pela tecnologia, comecei a seguir outros desenvolvedores e a conferir o trabalho deles no GitHub. Foi quando percebi algo que eles tinham em comum: todos eles tinham projetos interessantes e contribuíam com o código aberto, mas os projetos deles também tinham arquivos README detalhados.

Foi assim que meu interesse sobre o que era o README cresceu. Então, eu decidi tentar e adicionei um aos meus projetos, também. Não vou mentir – fiz o arquivo na corrida e sem nenhum conhecimento de como ele deveria ser feito. Honestamente? Não saiu lá grande coisa. Você pode conferir ele AQUI.

Foi assim que ele permaneceu durante um bom tempo. Porém, com a prática e o aprendizado contínuo, consegui transformá-lo em uma documentação melhor, deixando-o ASSIM, o que melhorou o engajamento com o projeto e ajudou a fazer com que outros desenvolvedores se envolvessem.

Também é importante observar que um bom README ajudará você a se destacar no meio da grande massa de desenvolvedores que colocam seus trabalhos no GitHub.

Neste artigo, ensinarei mais a respeito do que é um arquivo README e sobre como escrever um. Primeiro, vamos entender o que o arquivo README representa.

O que é um arquivo README?

De modo simplificado, podemos descrever um arquivo README como um guia que dá aos usuários uma descrição detalhada do projeto em que você trabalhou.

Ele também pode ser descrito como uma documentação com diretrizes para usar em um projeto. Em geral, ele terá instruções sobre como instalar e executar o projeto.

Sendo um desenvolvedor, é essencial que você saiba como documentar seu projeto escrevendo um bom README, pois:

  • É o primeiro arquivo que uma pessoa verá ao encontrar o projeto. Por isso, ele precisa ser breve, mas detalhado.
  • Isso fará com que seu projeto se destaque dos outros. Claro, não se esqueça de fazer um bom projeto.
  • Ele ajudará a priorizar as necessidades do projeto, quanto ao que precisa ser entregue e como fazer isso.
  • Escrevê-lo vai melhorar suas habilidades de escrita. Como disse Friedrich Nietzsche:
Um bom escritor possui não só o seu próprio espírito, mas também o espírito de seus amigos.

Enquanto estiver trabalhando em um projeto, lembre-se de que você precisará que outros desenvolvedores entendam seu código e o que ele faz. Assim, associá-lo a um guia adicional será muito útil.

Por exemplo, o exemplo que eu compartilhei anteriormente do meu primeiro projeto não tem um bom README. Mesmo que o projeto fosse incrível, seria difícil para um iniciante entender o que exatamente era esperado deles ao clonarem meu repositório. Ele podia até mesmo ser o código de um vírus.

Com um projeto como esse no GitHub, não importa que ele seja fantástico, outros desenvolvedores não terão o interesse de trabalhar nele e de tentar desvendar o que ele é sem um bom README.

Agora, vamos dar uma olhada nesse projeto. Aqui, você consegue entender o que o projeto faz, de que se trata, e como começar se você precisar usá-lo ou se quiser contribuir com o projeto.

Perceba o poder de um README bem escrito e como ele pode mudar seu projeto.

Bem, vamos começar a escrever um para você, também.

Como escrever um bom README: um guia passo a passo

Algo muito importante que se deve perceber é que não há uma maneira "certa" de estruturar um bom README. Existe, no entanto, um jeito "errado", que é simplesmente não incluir um README.

Partindo da pesquisa e do estudo de vários arquivos README, certamente existem práticas recomendadas que encontramos. Isso é o que pretendo compartilhar aqui. Eu costumo dizer para mim mesmo:

Todo dia é dia de aprender.

Assim, ao progredir e avançar em sua carreira, você desenvolverá suas próprias ideias sobre o que torna um README bom e sobre como melhorá-lo. Talvez você até crie o seu próprio guia.

Antes de começarmos, é importante observar que, quando você está escrevendo o README do seu projeto, você deve poder responder o quê, o porquê e o como relativos ao projeto.

Veja aqui algumas perguntas orientadoras para ajudar você:

  • Qual foi a sua motivação?
  • Por que você criou esse projeto?
  • Que problema ele resolve?
  • O que você aprendeu?
  • O que faz com que seu projeto se destaque?
    Se o seu projeto tem vários recursos, pense em adicionar uma seção "Recursos" e liste-os nela.

O que incluir no seu README

1. Título do projeto

Este é o nome do projeto. Ele descreve todo o projeto em uma frase e ajuda os outros a entenderem qual é o objetivo principal do projeto e seu intento.

2. Descrição do projeto

Este é um componente importante do projeto que muitos desenvolvedores iniciantes geralmente desconsideram.

A descrição é um aspecto extremamente importante do seu projeto. Uma descrição bem elaborada permite mostrar seu trabalho a outros desenvolvedores, assim como para empregadores em potencial.

A qualidade de uma descrição do README geralmente diferencia um projeto bom de um projeto ruim. Um projeto bom aproveita a descrição para explicar e exibir:

  • O que o aplicativo faz,
  • Por que foram utilizadas as tecnologias que estão no projeto,
  • Quais foram os desafios enfrentados e os recursos que se espera implementar no futuro.

3. Sumário (opcional)

Se o seu README for muito extenso, é interessante adicionar um sumário para facilitar a navegação entre as diversas seções. Isso torna mais tranquila a movimentação dos leitores pelas várias partes do projeto.

4. Instalação e execução do projeto

Se estiver trabalhando em um projeto em que o usuário precisa instalá-lo ou rodá-lo localmente em uma máquina como um "POS", você deve incluir as etapas para a instalação do projeto e quais as dependências necessárias, se houver alguma.

Forneça uma descrição passo a passo de como fazer com que o ambiente de desenvolvimento esteja configurado e funcionando.

5. Uso do projeto

Dê instruções e exemplos para que os usuários/colaboradores consigam utilizar o projeto. Isso tornará mais fácil para eles caso encontrem algum problema – eles sempre terão um local de referência para aquilo que se espera do programa.

Você também pode fazer uso de auxílios visuais, incluindo materiais, como imagens, por exemplo, exibindo o projeto durante a execução, bem como a estrutura e os princípios de design usados no projeto.

Além disso, se o projeto exigir autenticação, como senhas ou nomes de usuário, esse é um bom local para incluir as credenciais.

6. Inclusão de créditos

Se você trabalhou no projeto em uma equipe ou em uma organização, liste os colaboradores/membros da equipe. Você também deve incluir links para os perfis do GitHub e para as redes sociais deles.

Se você também seguiu tutoriais ou consultou determinado material que possa ajudar o usuário a criar aquele projeto específico, inclua aqui os links para esse material.

Essa é apenas uma forma de mostrar sua gratidão e também de ajudar outras pessoas a obter uma cópia em primeira mão do projeto.

7. Inclusão de uma licença

Para a maioria dos arquivos README, essa geralmente é considerada a última parte. Ela permite que outros desenvolvedores saibam o que podem e o que não podem fazer com seu projeto.

Temos tipos diferentes de licenças, dependendo do tipo de projeto em que você estiver trabalhando. Conforme sua escolha, ela determinará as contribuições que seu projeto receberá.

A licença mais comum é a GPL, que permite que outras pessoas façam modificações em seu projeto e que o utilizem para fins comerciais. Se precisar de ajuda na seleção de uma licença, confira este link: https://choosealicense.com/ (em inglês).

Até aqui, tratamos dos requisitos mínimos para um bom README. Você talvez queira considerar adicionar as próximas seções para torná-lo ainda mais atrativo e interativo.

Seções adicionais do README

8. Badges

As badges (insígnias) não são necessárias, mas usá-las é um modo simples de permitir que os outros desenvolvedores saibam que você sabe o que está fazendo.

Uma seção como essa pode ser útil para fazer o vínculo com ferramentas importantes, além de mostrar algumas estatísticas a respeito do projeto, como o número de forks, colaboradores, issues abertas etc...

Abaixo vemos uma imagem de um de meus projetos que mostra como você pode utilizar as badges:

check

O lado bom desta seção é o fato de que ela se atualiza automaticamente.

Não sabe onde obter as badges? Confira as que estão hospedadas em shields.io. Eles têm muitas badges para ajudar você a começar. Você pode não entender o que elas representam agora, mas entenderá com o tempo.

9. Contribuição com o projeto

Essa parte será mais útil se você estiver desenvolvendo um projeto de código aberto que precisará da contribuição de outros desenvolvedores. Você pode querer adicionar diretrizes para que eles saibam como podem contribuir com seu projeto.

Também é importante garantir que a licença que você escolheu para um projeto de código aberto está correta, de maneira a evitar conflitos futuros. Adicionar diretrizes de contribuição representam um papel importante.

Algumas das diretrizes mais comuns incluem o código de conduta de colaboração e o guia do colaborador (em inglês). Esses documentos darão a você a ajuda necessária ao estabelecer as regras para o seu projeto.

10. Inclusão de testes

Faça aquele esforço a mais e escreva testes para o seu aplicativo. Depois, forneça exemplos de código e como executá-los.

Isso ajudará a mostrar que você conhece seu projeto e tem confiança de que ele funcionará sem problemas, o que dará confiança aos outros sobre ele, também.

Pontos a mais

Aqui vão uns pontos extras a serem observados no momento de escrever seu README:

  • Mantenha-o atualizado - é uma prática recomendada garantir que seu arquivo esteja sempre atualizado. No caso de haver mudanças, não se esqueça de atualizar o arquivo quando necessário.
  • Escolha um idioma - Somos todos de zonas diferentes e falamos idiomas diferentes. Isso, contudo, não significa que você precise traduzir seu código para o idioma local. Escrever seu README em inglês está ok, já que ele é um idioma aceito no mundo todo. Pode ser que você queira usar uma ferramenta de tradução aqui se o seu público alvo não estiver familiarizado com o inglês.

Conclusão

Pronto! Tudo o que você precisa para melhorar os seus arquivos README ou começar a escrevê-los está aqui.

Neste ponto, tenho a confiança de que você conseguirá adicionar um guia interativo e informativo ao seu próximo projeto ou até a um projeto existente e fará com que seu projeto se destaque.

Há várias ferramentas que você também pode usar para gerar automaticamente um arquivo README para seu projeto, mas é sempre uma boa prática tentar isso por conta própria antes de passar para a automação. Caso você queira conferir algumas delas, aqui temos algumas delas (em inglês):

Se você leu até aqui, agradeço de coração. Se gostou do artigo e o achou útil, compartilhe-o para ajudar outros desenvolvedores a melhorarem seus projetos.

O autor gostaria de ver seu arquivo README recém-criado. Compartilhe com ele o link por meio de algum dos links abaixo:

Conecte-se com o autor pelo Twitter | YouTube | LinkedIn | GitHub

Compartilhe também sua opinião. Ela vale muito e o autor aprecia o seu feedback honesto!

Feliz programação! ❤