Texto de: Letícia Garcez
Introdução
O Github é uma ferramente que permite o armazenamento em nuvem de repositórios versionados com o Git. Neste artigo, não iremos falar sobre repositórios em si, mas sim sobre um arquivo especial que o GitHub destaca no seu repositório: o arquivo README. Esse é um arquivo com um título interessante que poderíamos traduzir para algo como “leia-me”, ou seja, um arquivo que deve ser lido antes de interagir com sua aplicação. Ele é escrito usando a linguagem markdown e por isso é comum vermos esse arquivo como README.md
Por que preciso de um README?
Se você está iniciando na área de tecnologia, pode até estar pensando que não precisa se preocupar com a criação de arquivos README porque usa o GitHub como uma espécie de Google Drive e porque ninguém acessa os seus projetos. Sinto te informar, mas esse é um pensamento um pouco problemático.
O arquivo README serve dois propósitos: o primeiro é apresentar o seu projeto para o mundo e o segundo é atuar como a documentação do seu projeto. Existem várias formas de documentar um projeto, mas a criação de um bom README costuma ser o suficiente para a maioria dos projetos, ainda mais se forem projetos que não contam com a colaboração de várias pessoas ao mesmo tempo.
Vamos falar um pouco do primeiro ponto: apresentar o seu projeto. Imagine uma galeria de arte com diversas pinturas, mas ao invés de estarem expostas para serem vistas facilmente, todas as pinturas estão guardadas em armários trancados a chave e para ver uma pintura você precisa primeiro achar a chave e destrancar o armário, mas todas as chaves estão juntas na mesma caixa e você terá que encontrar a chave correta na tentativa e erro. Visitar essa galeria não seria muito interessante, não é?
Pois quando você não adiciona um README no seu projeto, está fazendo mais ou menos isso, escondendo o seu projeto de todo mundo e fazendo com que seja ainda mais difícil ter acesso a ele. E em um mercado onde precisamos mostrar o que sabemos e o que somos capazes de fazer, isso pode acabar sendo um tiro no pé.
Agora, vamos focar no segundo tópico: documentação. A documentação de um projeto nem sempre é, e não deve ser, feita apenas para os outros. Claro que na maioria das vezes a documentação de um projeto é feita para ajudar outras pessoas a usarem o projeto, mas a documentação também ajuda você 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? Claro que você não precisa detalhar todo o seu projeto no README, mas uma visão geral, com informações relevantes, sempre é uma boa opção.
Após entendermos a importância dos READMEs, vamos ver alguns tópicos 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 não existe nenhuma regra aqui.
O que é este projeto
Esse tópico é bem simples de ser preenchido. O que é essa coisa que você desenvolveu? Qual o objetivo dela? É preferível que você informe 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 das funcionalidades do seu projeto, sem muitos detalhes. A ideia é que quem entre no projeto já saiba o que ele faz. Geralmente, a resposta desse tópico completa a resposta do tópico anterior, permitindo que você dê a quem estiver vendo o seu repositório uma noção geral do projeto.
Como rodar esse projeto
Mesmo que o seu repositório seja privado, sempre existe a possibilidade de você precisar voltar a trabalhar nele algum dia, e é bem provável que quando você precise rodar o projeto novamente, não se lembre de alguma informação ou configuração essencial para rodar o programa, como a configuração de um banco de dados, ou a instalação de um programa extra na sua máquina.
É uma boa ideia também preparar uma espécie de script para verificar se todas as dependências necessárias existem na máquina onde o programa vai ser rodado, e principalmente, quais comandos você precisa executar para colocar o projeto em funcionamento. 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 explicar 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 em especial pode ser merecedor da sua atenção.
Como este projeto foi implementado
Exponha as tecnologias que você utilizou para desenvolver o projeto, pode ser no formato de lista mesmo. Se quiser, você também pode especificar para que e por que usou cada uma das tecnologias e como elas foram utilizadas no projeto.
Como contribuir com este projeto
Se você deseja que outras pessoas contribuam com o seu projeto, esse é um tópico indispensável. Explicar como contribuir com o projeto é muito importante no mundo de projetos de código aberto, já que quem mantém o projeto pode estabelecer regras específicas para organizar melhor as contribuições.
Você pode adicionar essas informações dentro do próprio README, porém também é possível criar outro arquivo específico para as informações de contribuição chamado CONTRIBUTING.md caso você tenha informações demais para escrever nesse tópico. Também é possível que você queira colocar links extras nesse material, como links para um tutoriais de como fazer um pull request, ou deixar algum tipo de contato para que alguém interaja com você de maneira mais direta.
Referências e links úteis
Adicionar algumas referências que foram importantes para o desenvolvimento do seu projeto pode ser muito útil, especialmente em projetos que você está fazendo para aprender algo novo. Isso facilita não só se você precisar acessar aquele conteúdo novamente no futuro, mas 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.
Considerações finais
Os tópicos apresentados nesse artigo são bem básicos. Existem diversos exemplos de README que abordam tópicos completamente diferentes dos apresentados aqui, mas se você começar a trabalhar seus READMEs para ter pelo menos alguns dos tópicos listados nesse artigo, você já terá um projeto muito mais atrativo e bem documentado.
