Como criar um README incrível para seus projetos (e perfil) no Github

Programador(a), como está o README dos seus projetos no Github?

Ter um bom README pode aumentar suas chances de conseguir sua super vaga de programação quando um recrutador visitar o seu perfil, aumentar o uso das ferramentas que você criou e disponibilizou lá ou simplesmente fazer o dia a dia da sua equipe mais fácil na hora de usar um projeto (através das instruções deixadas lá)

Neste tutorial você vai aprender como criar um README de qualidade que vai melhorar a visibilidade e compreensão do seus projetos no Github.

Também teremos um BÔNUS ensinando como realizar um README próprio pro seu perfil do Github, ou seja, uma página de apresentação profissional no Github para que toda nova visita em seu perfil possa saber mais sobre você. Incrível, não?!

Mas você sabe o que é o README??

O README nada mais é que um arquivo de apresentação. É o “primeiro passo” ao abrir um novo projeto, seja pra ver a documentação, dicas essenciais que precisa saber para rodar o projeto, descrição de seu projeto, etc. Tudo isso pode e deve ser adicionado no README!

Um outro detalhe importante, o README é um arquivo markdown (.md), o markdown é uma linguagem de marcação que serve para apresentar informações de forma organizada (como o HTML).

E de forma similar ao HTML, o markdown também possui Tags, vamos comparar alguns exemplos:

HTML:

Markdown:

Nesse artigo, então, iremos:

1. Aprender como organizar, construir e estruturar um Readme estiloso e de fácil entendimento.
2. Construir um Readme de apresentação para seu perfil no Github! (BÔNUS)

Então, sem mais enrolação, bora lá!

Passo a passo

1. Por padrão, muitos projetos já vem com um arquivo README.md (como no caso de projetos Ruby On Rails).
Caso você não possua nenhum projeto ainda, crie um repositório no Github, crie um arquivo README.md e suba os códigos para lá.
Se você estiver em um projeto Ruby On Rails, ao abrir o README.md dele no Github você deve ver algo como:

2. Vamos clicar na caneta, na direção do título “README.md”, para editar o arquivo. Ele se apresentará da seguinte forma:

3. Então, vamos substituir pela seguinte estrutura:

4. Repare que nessa estrutura precisaremos dos seguintes itens:
– Logo do projeto.
– Prints das telas principais do projeto.

5. A boa impressão sempre parte do visual de nossas apresentações, e o primeiro contato que o recrutador ou a pessoa alvo terá se deparando com nosso projeto, então mãos na massa e bora lá!!

Para as logos, particularmente gosto de gerar no link abaixo:

https://pt.freelogodesign.org

6. Entrando no endereço, você deve digitar o nome do seu projeto, o ramo e clicar no botão “iniciar”:

7. Assim, abrirá uma tela com uma listagem de logos prontos para serem personalizados e utilizados. É só escolher o que mais gostou e clicar em “Adicionar”.

8. Personalizando, é só clicar em “Finalizar”, no canto direito superior!!

9. Aqui, clique em “Baixa resolução” para baixar gratuitamente. Aí é só digitar seu nome e email e a logo vai direto pra sua caixa de email!

10. Show!! Agora vamos tirar alguns prints das principais telas do nosso projeto! Rode o seu projeto em desenvolvimento e tire alguns prints, mas capriche bem!

Uma ferramenta muito boa para auxiliar nesse processo é o LightShot. Você pode baixá-lo no link abaixo:

https://app.prntscr.com/pt-br/download.html

11. Com as imagens capturadas, vamos ver o que temos:

12. Agora vamos no nosso projeto e adicione essas imagens em alguma pasta no nosso repositório. Para isso, particularmente gosto de deixar uma pasta chamada readme_images dentro da pasta public.

Bom, entre na pasta escolhida, no repositório do Github, e selecione Add file > upload files.

13. Arraste as imagens que obtivemos para essa pasta.

14. Assim que tudo for carregado, role a página até a parte inferior e clique em commit changes.

15. Você será redirecionado para a página principal. Vamos entrar na pasta que realizamos o upload. Ela terá que mostrar os arquivos salvos.

16. Abra a imagem da sua logo e copie a URL. Ela será importante no nosso readme.


17. Volte na raiz de nosso projeto e clique no ícone da caneta do nosso readme, no README.md, e vamos editá-lo novamente:

Mãos na massa!

18. Substitua:

Pela URL da sua logo, dentro da pasta que fizemos o upload.

Deve ficar com o seguinte formato:

19. Agora vamos substituir as informações genéricas por informações de nosso projeto:

Obs: Nesse passo será um bônus se você preencher as informações em inglês. Sendo linguagem universal, além de mostrar que você possui domínio na língua, ainda torna seu portfólio universal, tendo maior alcance!

20. Em How to Use iremos adicionar os prints que tiramos. Aqui será adicionado o conteúdo principal, o ouro do nosso projeto. Aqui faremos a identidade visual do nosso readme. Deixe-o mais ou menos no seguinte formato:

21. Em Features você vai adicionar tudo o que seu projeto faz. Ressalte as qualidades dele e mostre o potencial do projeto:

22. Em Links, substitua o link do seu repositório e adicione o link do deploy. Como o nosso projeto não possui deploy, vamos deixá-lo nesse formato:

23. Por fim, em Authors, substitua com suas informações. O nosso ficou desse jeito aqui:

24. A segunda parte de nosso readme ficou no seguinte formato:

25. E é isso!!! Role a página para baixo, e clique em “commit changes”.
Você será redirecionado para a página do seu Readme e se parecerá com o seguinte formato:

Bônus (README de perfil)!!!!!!

26. O Github lançou uma atualização para uma melhor apresentação do seu perfil na plataforma.

27. Primeiro, crie um repositório com as seguintes configurações:

28. Em repository name coloque o seu nome de usuário do Github. Coloque ele Público e inicializando com o Readme. Assim, clique em “create repository”.

29. Seu repositório se parecerá com o conteúdo abaixo:

30. Clique para editar o README e cole o seguinte conteúdo:

(Lembre-se de substituir as variáveis “link_do_seu_perfil_no_github”, “link_do_seu_perfil_no_linkedin”, “seu_telefone_55+DDD+número_de_telefone” e “seu_email” pelos seus dados pessoais correspondentes às variáveis).

31. Nosso readme ficou da seguinte forma:

32. Role a página para baixo e clique em commit changes. Acessando a página principal do seu perfil, ele estará mais ou menos da seguinte forma:

33. Pronto, seu perfil já está disponível no Github o/

Conclusão

Curtiu este artigo Programador(a)?
Saber escrever um bom README  e ter um perfil no Github pode te levar para o próximo level o/
Se você gostou compartilhe o artigo com outros(as) programadores(as) e deixe um comentário para gente 🙂

Caso você tenha interesse em projetos Open Source, acesse nosso artigo sobre: Como e por que contribuir com projetos Open Source

Muito obrigado por estar com a gente o/

Programador(a), uma pergunta importante!

Você sente verdadeiramente que é um Programador(a) completo(a)?

Por muito tempo eu fiquei em dúvida se eu estava pronto ou não e essa insegurança me levou a pesquisar profundamente sobre o que realmente é necessário para ser um programador web completo.

Depois de fazer muitos treinamentos, ler muitos livros, conversar com outros desenvolvedores, ir a eventos e até trabalhar em empresas do Brasil e do exterior foi que eu pude encontrar as bases fundamentais para ser um programador Web com confiança (sem medo de buscar jobs e assumir grandes projetos).

Eu peguei todo esse conhecimento e somei com toda a didática que eu aprendi criando cursos e tutoriais que são acessados por milhares de pessoas todos os meses e criei um treinamento chamado Programador Full Stack Javascript.

Nele eu vou te mostrar o ‘caminho das pedras’, ou seja, o essencial para você dominar a programação web, se sentir mais completo(a) e conseguir o seu tão merecido Job de respeito.

Então se você quer evoluir de verdade (sem perda de tempo), clica no link abaixo e conheça o treinamento agora.

Link: Programador Full Stack Javascript em 8 semanas ->