Encontre o README Perfeito Aqui

Já se deparou com aquele projeto que possui uma proposta matadora, que tem tudo pra crescer na comunidade open source e o código não ta uma bagaceira mas um README precário faz até perder a vontade de participar? Ou ainda quando você é quem está criando esse projeto mas tem preguiça de documentar o README ou nem mesmo sabe por onde começar? Esse era eu tempos atrás.

Aqui eu trago uma solução que criei após algumas pesquisas e coletas de dados: um README que dê gosto e curiosidade em quem lê. Tenho certeza de que você não vai se arrepender de continuar a leitura.

Conteúdo

Em resumo, o template que trago aborda as seguintes seções: Descrição, Stack, Arquitetura, Execução, To-Do List, Contrib e Licença:

1. Descrição: apresenta o projeto de forma objetiva em uma linha, seguida de uma descrição multi-linha detalhada do projeto, objetivo, razão de criação, problemas que resolve, etc.;
2. Stack: agrupa as tecnologias aplicadas de forma lógica, separando por linguagem, contexto e aplicação;
3. Arquitetura: demonstra o que alguém precisa saber sobre o funcionamento do projeto em uma visão macro, tanto na arquitetura de diretórios quanto o escopo do projeto;
4. Execução: lista os comandos que o projeto aceita/executa, junto à ação que cada comando realiza, desde um linter à transpilar JS em TS, por exemplo;
5. To-Do List: lista os próximos passos a serem seguidos, bem como as ações que já foram realizadas, conforme necessidade.
6. Contrib: apresenta o padrão de contribuição desejado para quem desejar realizar um PR, necessário para situações onde os padrões devem ser mantidos (quase sempre);
7. Licença: indica a licença a qual o repositório está submetido, contendo link para o conteúdo da licença caso haja necessidade de maiores informações sobre ela.

Observações

Quanto ao modelo fornecido abaixo, é importante ressaltar que as informações presentes são dados mockados, fictícios, e por esta razão se faz necessário revisar o template a fim de editar os dados para os reais de cada projeto.

Destaco dessa forma, portanto:

• Logo e path para o arquivo
• Badges de licença e workflow (GitHub Username e GitHub Project Name)
• Badges da Stack (remover os não utilizados, inserindo os necessários)
• Variáveis de Ambiente
• To-Do List (definir as metas reais, batidas ou não)
• Licença (escolher a descrição adequada para a licença escolhida)

Utilitários

Caso tenha pulado todo o conteúdo, o que particularmente não recomendo, fique agora com o link do template, junto com demais links que o auxiliem na adaptação do README ao seu projeto:

• Template: https://github.com/LucasGoncSilva/perfect-readme-template
• Choose a License: https://choosealicense.com/
• Arquivos de Guia Para a Comunidade: https://github.com/jessesquires/.github
• Badges Prontos Para Uso: https://github.com/Ileriayo/markdown-badges

Contrib

Fique à vontade para realizar contribuições com o template, aperfeiçoando-o e tornando-o cada vez melhor, seja com seções interessantes para acrescentar ou novas tecnologias dentro da seção Stack, ou ainda uma forma diferente de organizar alguma coisa, como por exemplo onde listar os contribuidores do projeto!