Que o Github é uma ferramente essencial para qualquer pessoa desenvolvedora, todos nós sabemos. Porém, o que muita gente não sabe (ou prefere ignorar) é que o README dos seus projetos no Github faz muita diferença na apresentação do seu perfil. Por isso, trago ideias pra você tentar melhorar seus READMEs, deixando-os mais descritivos.

Porque eu preciso de um README?

Se você está iniciando na área de programação, pode até estar pensando “mas eu só uso o GitHub pra guardar meus códigos e ninguém acessa meus projetos…”. Sinto te informar, mas temos um problema com esse pensamento ai!

A documentação de um projeto nem sempre é algo “feito para os outros”. Claro que muitas vezes a documentação é feita para ajudar outras pessoas a interagir com o seu projeto, mas uma boa documentação também ajuda você mesmo a interagir com seu próprio projeto. Quem nunca abriu um projeto depois de alguns meses e não fez a mínima ideia do que estava acontecendo naquele código?

O README em si, além de apresentar o seu projeto, muitas vezes é a única coisa que faz a documentação do projeto. Isso é muito comum em projetos pessoais, e por isso é muito importante prestar atenção nele, por menor que seja o projeto. Mesmo nos projetos privados.

Então prepare-se para algumas coisas que você pode incluir no README do seu projeto para torná-lo mais fácil de se entender, interagir e replicar; lembrando que são apenas ideias, e que não existe nenhuma regra aqui.

O que é este projeto?

Essa é uma pergunta simples e rápida. O que é essa coisa que você desenvolveu? Qual o objetivo dela? É preferível que você informe que seu projeto é para quem estiver lendo seu README o que seu projeto é do que forçar essa pessoa a olhar vários arquivos de códigos (que muitas vezes não são de fácil entendimento) para descobrir.

O que esse projeto faz?

Neste tópico, você pode fazer uma descrição breve do seu projeto, sem muitos pormenores. A ideia é que quem entre no projeto já saiba o que ele faz. Geralmente, esta pergunta completa a pergunta anterior, e permite que você dê a quem estiver vendo o seu repositório uma noção geral do seu projeto.

Como este projeto funciona?

Mesmo que o seu repositório seja privado, nada impede que você o torne público um dia, e aí outras pessoas vão querer rodar seu código. Além disso, é bem provável que o “seu eu do futuro” já não tenha mais alguma informação relevante para rodar o programa.

É uma boa ideia também especificar comandos para verificar se as suas dependências existem ou não na máquina de quem estiver tentando rodar sua aplicação (ou adicionar um arquivo com essas informações), e principalmente, quais comandos você precisa para seu projeto rodar. São dois cliques em um executável? Um comando específico no terminal? Alguma execução em um plugin de uma IDE específica?

Como utilizar este projeto?

Talvez este tópico soe um pouco redundante com o tópico acima, mas nesta parte do seu README, você deve se concentrar em dizer para a pessoa que quer interagir com seu projeto como interagir com o programa depois que ele foi aberto.

Supondo que o seu projeto seja uma ferramenta de linha de código, quais comandos fazem o quê? E se for algo com interface gráfica, como você pode realizar uma tarefa específica com esta aplicação? Nem sempre nossas criações são intuitivas para outros usuários, então este tópico pode ser especialmente merecedor da sua atenção.

Como este projeto foi implementado?

Exponha as tecnologias que você utilizou para desenvolver o projeto. Se quiser, pode especificar para que e porquê usou cada uma e explicar brevemente como implementou o projeto.

Como contribuir com este projeto?

Se o seu projeto for de uma lista de vagas ou um aglomerado de conteúdos, por exemplo, talvez você queira considerar um pequeno tutorial de como alguém deve formatar suas contribuições, e talvez até incluir um link para um tutorial de como fazer pull request, ou deixar algum tipo de contato para que alguém interaja com você de maneira mais direta.

Referências e links úteis

Pode ser muito útil adicionar algumas referências que foram importantes para o desenvolvimento do seu projeto, especialmente naqueles que você está fazendo para aprender algo novo. Isso facilita não só se você precisar acessar aquele conteúdo novamente no futuro, mas também dá muito mais recursos para a pessoa que está acessando seu repositório entender como as coisas funcionam.

Uma sessão de links úteis deixa o seu projeto muito mais fácil de ser entendido, replicado, e também ajuda muitas pessoas que podem ter interesse no seu projeto a aprender mais e entender melhor como as coisas funcionam.

Os tópicos que eu apresentei são bem básicos, e com certeza você encontra descrições mais detalhadas e exemplos de READMEs para seguir com facilidade, se tiver interesse nisso, porém, se você contemplar alguns tópicos desta lista para começar, já vai ter um projeto muito mais atrativo e bem documentado!

Espero que este artigo tenha te ajudado de alguma maneira, até mais e bons estudos!