Concrete Logo
Hamburger button

Como deixar o README do seu repositório profissional

  • Blog
  • 27 de Março de 2017
Share

*Este post foi originalmente publicado no CocoaAcademy (em inglês). Confira aqui.

Os readmes dos repositórios sempre tiveram um grande apelo pra mim. Todos eles vêm de diferentes formas, com imagens, gifs, bagdes, links e diversas outras coisas. Mais do que só parecer, eles realmente mostram um monte de informações sobre o que está acontecendo com o projeto, e puxam atenção para ele. Infelizmente, muitos de nós (pelo menos no início do projeto) não gastam tempo com os Readmes do repositório, mas hoje vou mostrar como mudá-lo para parecer mais profissional do que nunca.

Antes: ele era triste =(

lioy1

No screenshot você pode ver como o meu repositório do post do App da Marvel aparece. Não tem nenhum apelo real. Pra mim, é só um lembrete de uma oportunidade de compartilhar mais informação sobre meus objetivos e meu projeto.

*Se você ainda não viu a série de posts sobre o app da Marvel, pode começar por aqui. Você vai achar um monte de conteúdo legal sobre como criar um app do início, usando várias pods e ferramentas diferentes que farão sua vida muito mais fácil.

Então me mostre um melhor!

lioy2 lioy3 lioy4

Tem várias coisas diferentes neste README, vamos enumerar:

– Agora ele tem badges, mostrando informações relevantes no início;
– Tem uma navegação por âncora, o que permite que o leitor pule seções específicas;
– Tem um screenshot mostrando o fluxo da aplicação e o que o usuário pode esperar do projeto;
– Tem uma seção de motivação, que responde algumas questões como: o que é isso? Por que eu deveria me importar? Como esse é diferente dos outros? Quais são os meus objetivos com este repositório?
– Tem links para os posts, o que traz contexto à página;
– Tem seções de instalação e teste, o que traz instruções sobre como passar por esses passos;
– Por último mas não menos importante, tem uma seção de licença, mostrando a disponibilidade do código.

Tudo isso pode ser tão extenso quanto você achar que deveria ser. Você pode usar alguns dos seus projetos open source favoritos como inspiração para seus próprios repositórios. Se você quiser ver essa página no Github, clique aqui.

Fontes de pesquisa para seu README

Abaixo vou te mostrar algumas pesquisas que podem ajudar você na transformação do seu repositório. Vale a pena dar uma olhada! A shields.io, por exemplo, é uma ferramenta fantástica. Com a URL do seu repositório, ela sugere badges com base nos seus arquivos.

A Codecov e a Coversalls pode mostrar a porcentagem de cobertura do seu código como um badge personalizado. Ótimo!

Para finalizar

O resto é quase um passo-a-passo. Você pode ajustar e mudar seu README.md o quanto você quiser. Exitem várias ferramentas que podem te ajudar a ver o preview das mudanças localmente antes de mandá-las ao repo, o que é ótimo. Esta extensão do Chrome faz exatamente isso. A ideia desse post é só começar a discussão, você pode fazer muito mais com seu README.md.

Como sempre, se tiver dúvidas, comentários ou feedbacks eles são muito bem-vindos! Aproveite os campos abaixo.

É desenvolvedor e quer fazer parte de um time ágil de verdade e multidisciplinar? Clique aqui.