Como construir um README no GitHub que atraia recrutadores
Ter um README.md do GitHub bem estruturado pode ser um divisor de aguas entre atrair a atenção de recrutadores e conseguir sua vaga como dev.
O arquivo README.md é um componente essencial de qualquer repositório GitHub. É basicamente a documentação do seu projeto, um cartão de visitas, ele fornece informações importantes sobre o projeto para quem visita o repositório, incluindo desenvolvedores que podem querer colaborar, usuários que estão interessados em usar o software e recrutadores, pois cada projeto no seu GitHub é uma vitrine de suas experiências
A apresentação do README desempenha um papel crucial ao oferecer uma visão geral do projeto e ao demonstrar a habilidade do desenvolvedor em comunicar suas ideias e contribuições de forma eficaz.
No entanto, nem todos os READMEs são igualmente eficazes em chamar a atenção dos recrutadores. Este artigo busca explorar as estratégias mais eficientes para criar um README que se destaque no contexto da contratação em projetos de desenvolvimento de software.
Um estudo qualitativo foi conduzido, utilizando uma abordagem que envolveu a análise de documentações README de projetos de código aberto hospedados no GitHub. Foram escolhidos projetos frequentemente mencionados em processos de recrutamento na área de desenvolvimento de software para análise.
A partir dessa seleção, foram identificados os elementos comuns em documentações README que se destacaram pela clareza, organização e utilidade para os recrutadores. Com base nessa análise, foi criado um checklist com dez elementos considerados fundamentais para uma documentação README eficiente.
O checklist proposto inclui os seguintes elementos:
- Título Descritivo: Um título claro que descreve o propósito do projeto.
- Visão Geral do Projeto: Uma breve introdução que fornece uma visão geral do projeto.
- Instruções de Instalação: Passos claros e concisos para instalar e configurar o projeto.
- Exemplos de Uso: Exemplos práticos que demonstram como usar o projeto em diferentes cenários.
- Contribuições e Diretrizes: Orientações para contribuidores, incluindo diretrizes de contribuição e código de conduta.
- Licença: Informações sobre a licença do projeto para garantir conformidade legal.
- Status do Projeto: Indicação do estado atual do projeto (por exemplo, em desenvolvimento, estável, arquivado).
- Contato: Informações de contato do mantenedor do projeto para suporte e colaboração.
- Referências e Documentação Adicional: Links para recursos adicionais, como documentação detalhada, tutoriais ou FAQs.
- Agradecimentos: Reconhecimento aos contribuidores e projetos de código aberto utilizados.
O “.md” vem de Markdown , que é uma linguagem de marcação leve que foi criada para ser fácil de ler e escrever, enquanto ainda permite a conversão para HTML. Ele é comumente usado para formatação de texto em diversos contextos, incluindo páginas da web, documentação de software, mensagens em fóruns e, é claro, arquivos README.md no GitHub
Agora precisamos entender um pouco sobre os principais elementos de formatação markdown para que você possa usar a criatividade na hora de escrever seu README.md:
Títulos (Headers): você pode criar títulos usando #. Quanto mais # você usar, maior será o título:
# Título 1
## Título 2
### Título 3Ênfase (Emphasis): Você pode enfatizar o texto usando asteriscos (*) ou sublinhados (_):
*Texto em itálico*
**Texto em negrito**
_Outro texto em itálico_
__Outro texto em negrito__
Links (Links): Você pode criar links usando colchetes [] para o texto do link e parênteses () para o URL do link.
[Texto do Link](https://www.exemplo.com)Blocos de Código (Code Blocks): Você pode destacar blocos de código usando três apóstrofos (`) ou três til (~) no início e no final do bloco.
``` console.log('Hello, world!'); ```Listas (Lists): Você pode criar listas ordenadas e não ordenadas usando números ou asteriscos (*).
- Item 1
- Item 2
- Item 31. Item A
2. Item B
3. Item CCitações (Blockquotes): Você pode criar citações usando o sinal de maior (>).
> Isso é uma citação.Linhas Horizontais (Horizontal Rules): Você pode criar linhas horizontais usando três ou mais hífens (-), asteriscos (*) ou sublinhados (_).
---Template
Abaixo esta um template que eu costumo utilizar em todos os meus projetos, basta que você substitua as partes que mencionam "NomeDeUsuario" para seu nome de usuario no GitHub e "NomeRepositorio" para o nome do seu repositorio, e tudo ira funcionar, mas sinta-se livre para editar da forma que achar melhor!
# [Titulo do seu projeto]
> Descrição do projeto "Um web app, desenvolvido em xxx, utilizando o framework xxx com o intuito de resolver o problema xxx"
[](https://github.com/NomeDeUsuario)[](#)[](https://github.com/NomeDeUsuario/NomeRepositorio/stargazers)[](https://github.com/NomeDeUsuario/NomeRepositorio/network/members)[](https://github.com/NomeDeUsuario/NomeRepositorio/graphs/contributors)
# :pushpin: Sumario deste projeto
- [Features](#rocket-features)
- [UI Interface do Usuario](#framed_picture-ui-interface-do-usuário)
- [Guia de Instalação](#construction_worker-guia-de-instalação)
- [Vamos começar](#runner-vamos-começar)
- [FAQ](#postbox-faq)
- [Encontrou algum bug?](#bug-bugs)
- [Contribuição](#tada-contribuição)
- [Licença](#closed_book-licença)
<br />
# :rocket: Features
- Liste aqui todas as funcionalidades do seu projeto
- Autenticação social com Google e Meta
- Conexao com api externa xxx
- Imagens hospedado na AWS
# :framed_picture: UI Interface do Usuário
Documentação visual do projeto "Aqui voce pode colocar imagem das principais telas do seu projeto, um Gif dele funcionando e melhor ainda". troque o caminho abaixo pelo caminho da sua imagem
<p align="left">
<!-- <img src="src/images/mockup.png" /> -->
</p>
# :construction_worker: Guia de instalação
**Voce precisa instalar [NPM](https://www.npmjs.com/) ou [YARN](https://yarnpkg.com/) primeiro, para clonar este repositorio via HTTPS, ronde o comando abaixo:**
`git clone https://github.com/NomeDeUsuario/NomeRepositorio.git`
URLs SSH fornecem acesso a um repositório Git via SSH, um protocolo seguro. Se você tiver uma chave SSH registrada em sua conta do Github, clone o projeto usando este comando:
`git clone git@github.com:NomeDeUsuario/NomeRepositorio.git`
**Instale as dependencias**
Você precisa instalar as dependencias deste projeto, entao **execute o comando abaixo na pasta raiz**:
`yarn`
ou
`npm install`
# :runner: Vamos começar
Execute o seguinte comando para iniciar o app em um ambiente de desenvolvimento:
`yarn dev`
ou
`npm run dev`
Abra o navegador e vá para `http://localhost:3000`.
# :postbox: FAQ
**Pergunta:** Quais tecnologias foram utilizadas neste projeto?
**Resposta:** As tecnologias utilizadas são: [React JS](https://pt-br.reactjs.org/), [Typescript](https://www.typescriptlang.org/) and [Next.JS](https://nextjs.org/)
# :bug: Bugs
Sinta-se à vontade para **registrar um novo problema** com o respectivo título e descrição no repositorio [NomeRepositorio](https://github.com/NomeDeUsuario/NomeRepositorio/issues). Se você já encontrou uma solução para o seu problema, **adoraria revisar sua solicitação de pull request**! Dê uma olhada em nosso **gia de contribuição abaixo**.
# :tada: Contribuição
### Se você quiser contribuir para este projeto, siga estas etapas:
1. Faça um fork do projeto.
2. Crie uma branch para a sua feature `git checkout -b feat/NomeDaSuaFeature`.
3. Faça commit das suas alterações `git commit -am "[add/edit/del]/feat: Descrição da feature"`.
4. Faça push para a branch `git push origin feat/NomeDaSuaFeature`.
5. Crie um novo Pull Request.
# :closed_book: Licença
Lançado em 2024.
Este projeto esta sob a licença [MIT license](https://github.com/NomeDeUsuario/NomeRepositorio/master/LICENSE).
Se você tiver alguma dúvida ou sugestão, entre em contato atravésdo email: [seu-email@example.com](mailto:seu-email@example.com). Resultado
Assim ficará quando alguém visitar seu repositório no GitHub:
Dica: Copie este template e guarde em um arquivo de bloco de notas, e sempre que você criar um repositório novo, você apenas copia e cola no arquivo README e altera as informações de nome do repositório, assim mantendo uma documentação bem escrita e fácil de entender e de utilizar!
Além do exemplo que apresentei nesta edição, há várias ferramentas online disponíveis para auxiliar na criação de um README atraente. Aqui estão algumas opções que experimentei:
- Readme.so: Um site intuitivo com um editor de Markdown e modelos de README prontos para usar em seus projetos.
- Make a Readme: Um guia que oferece assistência na redação de um README para o seu projeto, com instruções de uso em diversos repositórios populares e um modelo editável para começar.
- ChatGPT: Esta ferramenta pode coletar informações sobre o seu projeto, como descrição, tecnologias utilizadas, instruções de instalação, uso e contribuição, entre outras. Com esses dados, o ChatGPT pode ajudar na elaboração de um README detalhado e bem estruturado.
É importante lembrar que o arquivo README serve como uma introdução ao seu projeto, representando apenas o primeiro passo em direção a uma documentação completa de software. Uma documentação abrangente pode incluir informações sobre a API, manuais do usuário, exemplos de código, FAQs e até mesmo vídeos tutoriais, dependendo da complexidade e escopo do projeto.
Dica de produtividade
Você pode usar o próprio editor do VS Code para editar e ver um preview ao mesmo tempo do seu arquivo README.md. Basta clicar com o botão direito no seu arquivo e escolher a opção "Abrir Visualização" ou "Ctrl + Shift + V".
Conclusão
Uma documentação README bem elaborada não apenas auxilia os recrutadores na compreensão do seu projeto, mas também evidencia profissionalismo e dedicação à excelência do seu trabalho.
Que a força esteja com vocês.