Como fazer um bom README para o seu GitHub

Capa

O GitHub se tornou o principal repositório de código fonte da atualidade. Neste post vou falar um pouco sobre um elemento importante dos projetos hospedados nesta plataforma que nem sempre recebe a devida atenção: o arquivo README.md.

Figura1_ReadMeQuando procuro um projeto ou código fonte é muito comum me deparar com um repositório no GitHub. Nestes momentos a primeira impressão que eu tenho do projeto ou do que foi feito é descrito no arquivo README.me que aparece logo de cara no repositório. Contudo, tenho visto muitos problemas neste arquivo que acabam me confundindo e não despertando o meu interesse pelos projetos.

Por causa destes problemas no arquivo README resolvi escrever este post falando um pouco sobre os itens que eu considero importantes para descrever corretamente um projeto no GitHub. Mas antes, faço um pouco de mea culpa: os repositórios do meu próprio GitHub não estão bem documentos e não seguem as recomendações que vou escrever aqui. Mas isso tem um bom motivo: geralmente eu trabalho com hardware, ambientes ou protótipos que não são disponíveis para o público geral e, por isso, estou mais preocupando em fazer o código funcionar do que transformá-lo em um projeto que possivelmente possa virar um produto ou que necessite de contribuições.

Figura2_Goals

O primeiro ponto que acho muito importante para o arquivo README de um repositório no GitHub é uma boa descrição do objetivo do projeto destacando rapidamente para que ele serve, qual é o seu contexto de uso, características principais e vantagens de utilização. Infelizmente, muita gente está correndo contra o tempo quando envia os arquivos para o Git e, por causa disso, não se concentra muito na descrição curta, rápida e simples do que o projeto é.

Existem alguns bons exemplos (como este) de arquivos README que enfatizam a lista de funcionalidades e até contém imagens, GIFs animados e outros recursos para destacar como o projeto é bacana, o que ele faz e, o mais importante, como ele pode te ajudar. Nestes casos fico feliz e contente em ver que o responsável pelo projeto teve o trabalho de fazer uma boa publicidade do que ele produziu logo no README, algo que com certeza o destaca entre outros projetos similares.

Figura3_Dependencias

Outro ponto importante são as dependências. Aqui já é possível identificar a tecnologia utilizada e o que é necessário para ela funcionar. Tenho visto também exemplos bacanas como este onde há preocupação de dizer como utilizar o projeto junto com gerenciadores de pacotes ou ferramentas de build como o Ant, Maven, Gradle, Pip, Peacle, etc.

Uma das coisas que me atrai logo de cara em um projeto hospedado no Git é um exemplo simples de uso. Este exemplo pode ser representado por algumas linhas de código, exemplos de chamada com parâmetros ou mesmo por uma lista de links que remeta a arquivos de código fonte do projeto com exemplo. De qualquer maneira, isso me passa a impressão que não vou ter muito trabalho para usar que está sendo disponibilizado no repositório. Sem contar que um exemplo já deixa claro o jeito de como as coisas funcionam e aspectos de tecnologia utilizados no projeto.

Figura4_Documentacao Um arquivo README deve ser bem resumido e não deve ser uma documentação geral do projeto. Isso, inclusive, pode ser indicado com um link que aponte para um JavaDoc, uma página Wiki ou mesmo listas de discussão ou fórum. Para mim é importante saber onde eu posso ir quando precisar de alguma ajuda técnica durante o uso do projeto.

Figura5_licensaUm projeto de software sempre deve ser associado à maneira legal de como ele dever ser utilizado por outros e acredito que é muito importante destacar no projeto qual é licença utilizada no README, pois não é porque um projeto está hospedado no GitHub que você pode utilizar o código fonte como bem entender. Existem diferentes tipos de licença e é importante ficar claro qual é utilizada no projeto para evitar complicações futuras.

Muitas vezes eu gosto muito de um projeto e me sinto compelido a contribuir com ele ou mesmo fazer uma doação. Nestes casos, às vezes fico frustrado por não encontrar este tipo de informação no README e, por causa disso, não sei bem ao certo como proceder para agradecer ou auxiliar de alguma maneira o projeto. Portanto, acredito que vale a pena investir em uma sessão com informações sobre como se envolver com a comunidade caso o projeto ainda esteja sem desenvolvimento.

Por fim, gosto de ver no final de um arquivo README de um projeto do GitHub uma sessão com agradecimentos às pessoas que contribuíram de forma direta ou indireta com o projeto. Isso mostra que há um reconhecimento de quem dedicou tempo ou outros recursos para tornar melhor o software, nem que seja ao menos como uma fonte de inspiração.



Esta entrada foi publicada em Programação, Uncategorized e marcada com a tag , , , , , , . Adicione o link permanente aos seus favoritos.

4 respostas a Como fazer um bom README para o seu GitHub

  1. Realmente, a pior parte dos meus códigos no GitHub é o readme e a documentação.

    Obrigado pelas dicas.

  2. Renan Rodrigues disse:

    Parabéns pelo post! Foi muito útil pra mim, pois ficamos tão “bitolados” em código, que esquecemos de alguns detalhes que são realmente necessários.

  3. Ótimo tópico!

    Algo que ainda facilita muito na construção de bons README’s é a questão de o Github aceitar a marcação markdown e organizar para ficar bem legível para quem precisa.

    Um rápido guia para a escrita markdown pode ser encontrada aqui [1].

    [1] – https://help.github.com/articles/markdown-basics/

  4. Obrigado pela orientação, bastante esclarecedora.

Deixe uma resposta

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *