Como escrever um README de um projeto no Github + Template gratuito de README para seus projetos

Introdução

Sabemos como é a sensação…

Você passa bastante tempo estudando e desenvolvendo um projeto, com várias tecnologias e o resultado é incrível.

Você decide postar no Github e descobre que, ninguém tá acessando o seu projeto.

Existe uma grande chance de o problema ser o README do seu projeto, sabia?

Tão importante quanto ter um bom código e criar uma boa documentação para ele, principalmente quando o trabalho é feito em equipe e/ou quando o código precisa ser constantemente atualizado. Uma boa documentação aumenta a legibilidade, permite identificar a lógica por trás do código e auxilia na detecção de erros.

É por essas razões que o tema deste artigo é justamente esse:

Como criar um bom README no Github

O que é um README de um projeto?

De maneira geral, é um arquivo de texto que fornece informações essenciais sobre o projeto. Geralmente escrito em formato Markdown, ele descreve o propósito, funcionalidades, requisitos, instalação, uso e contribuição do projeto. Serve como guia para outros desenvolvedores entenderem e utilizarem o projeto de forma eficiente.

Na prática, é um guia, para que todo mundo que acessá-lo, possa entender os detalhes do seu projeto e decidir colaborar com ele, caso seja Open Source, por exemplo.

Por que é importante ter um README para seu projeto no Github?

Ter um README para seu projeto no Github é importante por muitas razões, algumas delas são:

Ele atua como uma introdução ao projeto, fornecendo uma visão geral rápida do que é o projeto e do seu propósito. Isso é especialmente útil para desenvolvedores que estão explorando projetos em potencial e desejam entender o que o seu projeto oferece.

Além disso, o README é um local centralizado para fornecer informações importantes sobre o projeto. Você pode incluir requisitos de sistema, dependências, instruções de instalação e configuração. Isso ajuda os usuários a entenderem como configurar o ambiente de desenvolvimento para trabalhar com seu projeto e quaisquer etapas adicionais necessárias para que ele funcione corretamente.

Ter um README completo e bem estruturado também demonstra profissionalismo e dedicação ao projeto. Mostra que você se preocupa em fornecer documentação clara e útil para os usuários e colaboradores. Isso pode aumentar a confiança na qualidade do seu projeto e incentivar mais pessoas a usá-lo ou contribuir para ele.

Neste artigo, você não só aprenderá as melhores práticas para escrever um README no Github como poderá acessar, gratuitamente, um template que fizemos para facilitar a criação do README do seu projeto no Github.

A diferença entre o README de projeto e o de perfil.

É importante diferenciar o README de projeto e o de perfil.

O README de perfil serve como uma introdução ou um resumo do seu perfil profissional. É uma oportunidade para você se apresentar, destacar suas habilidades, projetos relevantes, interesses e outras informações que deseja compartilhar com a comunidade. Ele é exibido na parte superior da página do seu perfil e pode ajudar a atrair a atenção de outras pessoas que visitam seu perfil, como recrutadores, colaboradores em potencial ou membros da comunidade.

Fizemos um artigo inteiro sobre o README de perfil e você pode acessá-lo aqui.

Já o README de projeto é um arquivo comumente encontrado nos repositórios no GitHub. Ele inclui informações sobre o propósito do projeto, funcionalidades, requisitos, instruções de instalação, exemplos de uso, documentação adicional e qualquer outra informação relevante.

Enquanto o README de perfil é mais voltado para apresentação pessoal e divulgação das suas realizações e interesses, o README de projeto é voltado para a documentação e comunicação sobre um projeto específico.

Estrutura de um README de projeto: o template Cubos Academy.

Mas, a dúvida que fica agora é:

O que incluir no README do seu projeto no Github?

E a verdade é que, existem muitas formas de fazer a estrutura de um README no Github.

Mas, para facilitar a organização do README do seu projeto, criamos um template exclusivo para você.

Clique aqui para utilizá-lo

O template é composto por algumas partes, são elas:

Cabeçalho

O início do template, nesta seção, você pode colocar o nome, uma breve descrição e as pessoas que participaram deste projeto.

No “contexto”, é recomendável incluir alguma informação como o sprint do projeto ou o nome da empresa.

Você pode substituir o Header da Cubos Academy por uma logo da empresa em que trabalha ou do seu projeto.

Além disto, esta seção inclui algumas informações que são atualizadas de maneira automática pelo Github, como a quantidade de linguagens utilizadas, o tamanho do repositório e o mês em que foi feito o último commit.

Nome e Status

Logo abaixo do cabeçalho, é possível colocar novamente o nome do projeto, o status e alguns links relevantes.

Sobre o projeto

Uma seção dedicada a oferecer as informações gerais sobre o projeto, como, por exemplo, o contexto em que ele foi desenvolvido.

Esta seção ajuda a ter uma noção mais geral sobre o projeto, situando aqueles que estão abrindo a página pela primeira vez.

Funcionalidades

Aqui você inclui as funcionalidades e entidades do seu projeto.

Incluir essas informações pode ajudar as pessoas a entenderem melhor o objetivo, o funcionamento e a estrutura do seu projeto.

Layout

Uma seção para incluir o layout da sua aplicação, tanto para mobile quanto para web, facilitando assim a visualização da parte visual do seu projeto.

Como executar o projeto

Uma das seções mais importantes do template, aqui você pode incluir as informações para execução do projeto, incluindo os pré-requisitos, e as instruções do back e front-end.

Tecnologias

Nesta seção, você pode incluir as tecnologias e ferramentas utilizadas para a construção do projeto.

Isso é relevante, por exemplo, para as pessoas saberem se elas podem colaborar, utilizando as linguagens que você utilizou.

Contribuidores

Uma seção para descrever todas as pessoas que contribuíram com projeto.

Uma forma de reconhecer as pessoas envolvidas na construção do projeto e disponibilizar os seus respectivos contatos.

Como contribuir para o projeto

Aqui você pode incluir o passo a passo com as instruções para quem quiser contribuir com o projeto.

Autor

Na seção final do README, você pode incluir sua foto, seu nome e um link para contato.

Licença

E por último, mas não menos importante. É essencial incluir a licença do seu projeto.

Algumas dicas rápidas para garantir a eficiência do seu README de projeto.

Melhores práticas para criar um README eficiente: ser conciso, utilizar linguagem clara e objetiva, atualizar regularmente.

1. Utilize linguagem clara e objetiva e de maneira concisa.
2. Atualize regularmente.
3. Garanta que seus pré-requisitos estejam escritos de maneira clara.
4. Demonstre os comandos relevantes para a instalação.

Conclusão:

A importância de um bom README para atrair colaboradores e manter o sucesso do seu projeto no Github.

Programar é empreender, e você não quer que seus projetos incríveis nunca sejam lidos porque as pessoas não sabem como executá-los, ou pior, nem leem o README direito, por este não estar atrativo.

As melhores práticas para escrever um README no Github são relativamente simples, e você conheceu alguma delas hoje.

Criar um bom README no Github é essencial e fica ainda mais fácil com o template gratuito que disponibilizamos neste artigo.

Agora é sua vez, organiza o README dos seus projetos, posta no LinkedIn e não esquece de marcar a gente.

Sucesso!