[pt-BR] REDAMEs DO GITHUB: IDEIAS... E DICAS

Olá pessoas! Estou meio sumida, mas continuo viva, a quem interessar hehe.

Neste artigo, quero conversar com você, pessoa desenvolvedora, pessoa curiosa de tecnologia, pessoa que por ventura do destino está lendo este artigo, sobre algo muito importante para seus repositórios que ficam armazenados em alguma plataforma com controle de versão. Algo que muitas vezes não recebe a atenção que deveria, o README do seu projeto.

Porque eu preciso de um README?

Se você não trabalha com desenvolvimento profissionalmente, pode até estar pensando "mas eu só uso o github pra guardar meus códigos mesmo, ninguém acessa meus projetos", mas ai é que temos um grande problema.

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 ajuda você a interagir com seu próprio projeto também. Seja agora, ou no futuro. Caso você já tenha revisitado um projeto antigo, sabe do que eu estou falando. Quem nunca abriu um projeto e não fez a mínima ideia do que estava acontecendo, não é mesmo? Você com certeza ficou olhando aquele projeto e pensando porque não escreveu ao menos pra que aquele código servia.

Além desse problema óbvio, imagine que você tem um projeto que pode solucionar perfeitamente o problema de um colega, e quando ele abre seu projeto, tudo que esse colega vê são vários arquivos e pastas aparentemente sem muita relação lógica. Divertido, não é? Bom, ainda não é um problema muito grande, porque você tem contato com o colega, mas... E se for você que abre um projeto apenas com arquivos e pastas na tela, mas você não tem contato de quem criou aquele código?

Bom, com esse problema exposto, vamos embarcar na aventura de criar um README interessante para o seu projeto. Para nortear essa parte da documentação, quero que você se faça a seguinte pergunta para quem é este README?

Se você está desenvolvendo algo para você mesmo no futuro, pode tentar uma abordagem mais simples. Se está fazendo um projeto que apresentará como portifólio para uma entrevista de emprego talvez você queira manter uma clareza e detalhamento maior. Se seu projeto é um tipo de software que você quer que as pessoas baixem e usem seu foco vai ser mais nas funcionalidades do projeto. Se seu projeto é algo que tem grandes chances de ser replicado pela comunidade talvez você queira explicar como o projeto funciona e o que você tem que saber para modificá-lo. Tudo depende do "público alvo" do seu projeto, e do direcionamento que você quer dar para ele.

Vale a pena lembrar que eu não sou nenhuma expecialista em READMEs (inclusive, alguns dos meus projetos antigos estão sem README), mas tenho me preocupado bastante com isso ultimamente. Já que meus READMEs tem sido bastante elogiados, resolvi compartilhar um pouco sobre como faço essas documentações. Então vamos à uma lista com alguns tópicos que você pode considerar quando estiver escrevendo o README do seu projeto.

Tópicos para você escrever sobre:

O que é este projeto?

Uma pergunta simples e rápida. 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 do seu projeto, sem muitos pormenores. A ideia é que quem entre no projeto já saiba o que ele faz. Se você estiver navegando por repositórios antigos procurando algum projeto específico, a existência desse item no seu README pode fazer toda a diferença entre encontrar o que você procura rápido, ou não.

Como este projeto funciona?

Mesmo que o seu repositório seja privado, nada impede que você o torne público um dia, e ai outras pessoas vão querer rodar seu código. Além disso, é bem provável que o seu eu do futuro não vai estar mais usando o mesmo computador nas mesmas condições que você está usando hoje. Talvez tenha formatado o computador e falte alguma coisa essêncial para o funcionamento do seu programa, então é uma boa ideia lembrar o seu eu do futuro como rodar sua aplicação.

Eu, por exemplo, já tentei rodar uma aplicação Java em um computador que tinha sido formatado e não tinha o Java instalado. É 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, como você vai interagir com seu projeto? 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 como são para a gente, 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. Se seu projeto está sendo desenvolvido para uma entrevista de emprego, você já consegue mostrar ao avaliador o que você sabe, e se outro usuário for interagir com seu projeto, ele já sabe o que precisa entender para compreender a totalidade da aplicação. Se quiser pode expecificar 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 contatos, 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.

Deixando seu README atrativo

Bom, seu README agora contém várias informações úteis e relevantes para qualquer pessoa que queira interagir com seu projeto. MAAAASSSSS isso não é tudo. Existem várias outras coisas que podemos adicionar em um arquivo README para que você possa fazer uma pessoa que nunca viu seu projeto antes de apaixonar por ele, e sejamos justos, todo mundo quer estrelinhas no Github.

Imagens

Você tem imagens do seu projeto? Se sim, escolha algumas imagens bonitas do seu projeto, ou imagens que mostrem as funcionalidades que você implementou. Imagens que representem como você quer que seja a primeira impressão do usuário que está chegando no seu projeto pela primeira vez. Nos meus projetos de hardware, por exemplo, costumo colocar fotos da engenhoca funcionando, nos projetos web, prints do site.

Não tem nenhuma imagem relacionada ao projeto? Que tal desenvolver alguma coisa no Canva para dar uma certa personalidade ao seu projeto? Esse site oferece uma infinidade de designs bonitos para você modificar e fazer coisas lindas (a capa desde post, inclusive, foi feita no Canva). Acredite, se eu consigo fazer coisas bonitas com o Canva, você também consegue! Um banner com o título do seu projeto e uma breve descrição, por exemplo, deixa seu projeto com um aspecto muito mais interessante do que simplesmente vários parágrafos.

Uma coisa importante pra se falar aqui, é sobre o tamanho da imagem. É preferível que você edite o tamanho da sua imagem para diminuir o espaço que ela ocupa. Além de que imagens mais leves carregam mais rápido, não é muito interessante ocupar o espaço do seu GitHub com imagens. Eu costumo deixar uma pasta com algumas imagens nos meus projetos de hardware, apenas para que a pessoa que se interessou possa ver o projeto sobre outros ângulos (nesses casos, deixo informado no README que mais imagens do projeto se encontram em determinada pasta), sem precisar abrir nenhum link externo.

Mostre seu projeto funcionando

Se você tem como disponibilizar algum link para seu projeto funcionando, isso é ótimo. Geralmente para projetos web, uma página hospedada no GitHubPages ou algo hospedado no Heroku já podem mostrar à pessoa que está chegando no seu projeto como ele é lindo e maravilhoso.

Caso o seu projeto não seja um projeto web, talvez fosse legal você considerar algum tipo de documentação em vídeo, como por exemplo um vídeo curto do projeto funcionando. Você pode hospedar esses vídeos no youtube como não listado, por exemplo. Eu não recomendo de jeito nenhum que você armazene vídeos dentro do projeto. Vídeos ocupam um espaço desnecessário no seu repositório, e para assistí-los a pessoa precisa fazer o download do vídeo. Hospedar o seu vídeo em algum lugar da internet facilita o acesso dessa pessoa ao seu conteúdo.

Referências e links úteis

Adicione algumas referências que foram importantes para o desenvolvimento do seu projeto. Isso facilita não só se você precisar acessar aquele conteúdo novamente no futuro, mas dá muito mais recursos para a pessoa aleatória que está acessando seu repositório entender como as coisas funcionam.

Tem algum artigo que te explicou um conceito importante? Coloca o link. Usou uma paleta de cores específica? Coloca o link. Tem um vídeo que explica tudo que você precisava fazer? Coloca o link. 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.

Personalize seu README

Seu README não precisa ser apenas texto, e existem duas coisas que eu gosto muito para deixar meus READMEs mais dinâmicos: Badges (ou Shields) e Emojis.

Começando pelas bagdes, se você não conhece o Shields.io, clica no link e dá uma olhada. É um site que fornece diversos tipos de bagdes para você inserir nos seus READMEs, com diversos estilos diferentes. Se você tem um produto mais profissional no GitHub, inserir algumas destas badges fazem toda a diferença.

Além desse site, você também pode encontrar alguns badges legais nesse post do usuário Envoy-VC. Se tiver paciência, também pode adicionar icones do site simpleicons.com, porém eu acho essa útlima opção um pouco mais chata de ser incluida nos READMEs.

Já quando o assunto é Emojis, você pode visitar este repositório, onde você pode encontrar vários emojis, para decorar seu README da maneira que achar melhor.

Por um mundo com mais READMEs!

Espero que este artigo tenha te motivado, ainda que só um pouquinho a repensar os READMEs do seu projeto. E para finalizar este artigo, só quero deixar um tema para vocês pessoinhas que falam inglês, que é o o artigo da Ellaine Tolentino sobre mostrar o seu estilo no README do Github. Esse artigo, inclusive, foi o que me inspirou a (tentar) fazer READMEs bonitinhos para os meus projetos.

Então... Espero que esse artigo tenha sido útil de alguma forma, e se você tem mais dicas sobre READMEs, pode comentar que eu adoraria construir um diálogo em cima disso com as pessoas maravilhosas dessa comunidade!

Até a próxima!