Para projetos de código aberto (open source), um bom arquivo README pode diferenciar seu projeto de uma grande massa de outros projetos e aplicações parecidos.
E mesmo se o seu projeto não for open source, o README normalmente será a porta de entrada de qualquer desenvolvedor à rotina ou aplicação que seu projeto está se propondo a implementar. Imagine receber o projeto de alguém que você não conhece, ou por algum motivo não tem o contato. Seria muito difícil conseguir destrinchar e entender o funcionamento e as funcionalidades, e até mesmo contribuir com código novo e novas funcionalidades, possuindo acesso apenas ao código fonte.
Este artigo está dividido em uma série de 7 passos para facilitar a sua vida, e ao final está disponível um modelo de um arquivo README para você utilizar em seus futuros projetos. Então vamos lá.
1 - Descreva o objetivo do seu projeto
Pense no seu potencial usuário. De forma sucinta e clara, descreva qual objetivo do seu projeto, qual dor ou problema ele propõe a resolver.
Seja tão direto quanto possível em o quê o seu projeto faz para que o leitor possa decidir rapidamente se é o que ele está procurando ou não.
Aqui, um único parágrafo curto e sucinto é o suficiente para descrever essa seção.
Bônus: Adicionar uma imagem, ou ainda melhor, um GIF mostrando rapidamente o seu projeto "em ação" pode ser muito interessante também.
2 - Como instalar
Digamos que seu usuário decidiu que seu projeto vale a pena olhar.
Ou simplesmente ele é o desenvolvedor que herdou o seu código para dar continuidade ¯\_(ツ)_/¯.
Seja qual for o caso, o usuário do seu projeto precisará saber como utilizá-lo. Mesmo que seu projeto seja simples e direto, é bom documentar essa seção pois alguns usuários podem se sentir frustrados e até mesmo abandonarem por não conseguirem instalá-lo.
Escreva um "HOW TO" simples e direto, inclusive com quais os comandos devem ser digitados no terminal para que a instalação seja bem sucedida.
Caso o seu projeto funcione em mais de um sistema operacional, é interessante mencionar as possíveis diferenças entre as plataformas.
Além disso, descrever de forma resumida o porquê de utilizar algumas das suas dependências pode ser um fator importante para o seu potencial usuário, considere isso ao escrever essa seção do seu README.
3 - Exemplos
Caso seu projeto seja uma biblioteca ou trecho de código que vá ser embarcado em outra aplicação, escreva alguns casos de uso do seu projeto de forma que motive o usuário à utilizá-lo.
Aqui vale usar trechos de código, imagens, e quaisquer artefatos que mostrem seu projeto em ação.
4 - Como montar o ambiente de desenvolvimento?
O ponto em questão aqui é facilitar a vida do usuário do seu projeto. E normalmente é pelo ambiente de desenvolvimento que ele vai começar a ter os primeiros contatos com seu projeto. Em repositórios open source, o objetivo vai ser auxiliar potenciais contribuintes à montarem seu ambiente e iniciarem o desenvolvimento e motivá-los à contribuírem com o projeto.
Em projetos fechados é interessante pensar que alguém um dia vai herdar seu código, e pode ser bem frustrante não receber esse tipo de instruções por não saber por onde começar ou não ter determinadas informações-chave.
Essa seção deve deixar claras as respostas das seguintes perguntas:
Como instalar o ambiente de desenvolvimento e as dependências? Como executar uma suíte de testes?
Como garantir que o código está funcionando?
5 - Como contribuir?
Nesse tópico é interessante descrever o que fazer e como contribuir com o projeto. Esse tópico irá motivar potenciais contribuintes para seu projeto open source, e caso for fechado vai garantir que futuros desenvolvedores conscientemente sigam o padrão predeterminado e pensado do projeto.
Aqui você pode incluir uma breve descrição do processo de desenvolvimento geral. Por exemplo, o que escrever em uma pull request, como documentar o código, etc.
É interessante também nessa seção descrever como o usuário pode compilar e distribuir o seu projeto.
São criados instaladores da aplicação?
Como é feito o controle de versão?
Que tipos de testes devem estar presentes?
Quais os pré-requisitos de uma nova função ou trecho de código?
Pode ser bastante frustrante não saber como distribuir um projeto que você achou bacana e até mesmo implementou alguma contribuição.
6 - Histórico de mudanças (Changelog e badges)
Possivelmente os seus usuários irão querer (ou até mesmo precisarão) saber quais as últimas versões lançadas do seu projeto, e comparar as mudanças que ocorreram nessas versões (ou uma versão específica).
Algumas ferramentas de controle de versionamento podem ter essa funcionalidade, como a função RELEASES do GitHub, mas mesmo assim pode ser bem interessante descrever de forma breve as principais mudanças das versões do seu projeto.
Bônus: Adicionar badges de versão, compilação, compatibilidade, etc no início do README é um diferencial e dá uma aparência mais profissional;
7 - Informações de licença de uso e Autor
Informar sob qual licença seu projeto está resguardado é importante para esclarecer possíveis implicações legais no seu uso.
O GitHub ainda recomenda a inclusão de um arquivo LICENSE.txt na raiz do seu repositório, mas mesmo assim e até por uma questão de facilidade, é interessante deixar claro qual a licença que rege a utilização do projeto.
Se você tem dúvidas sobre qual formato escolher, um bom site para entender à fundo é o https://choosealicense.com/licenses/
Além disso, colocar informações sobre o autor do projeto e seus contatos pode ser interessante principalmente para projetos open source, de modo que seus usuários possam contatá-lo para eventuais dúvidas, problemas ou sugestões.
Template de um arquivo README
Espero que este artigo tenha esclarecido as suas dúvidas à respeito de como descrever seu projeto no arquivo README, e com um pouco de sorte tenha te ensinado um ou mais novos conhecimentos à respeito desse importante tema.
Abaixo segue um link de um template de arquivo README para você reaproveitar nos seus projetos.
A ideia desse artigo surgiu da necessidade de avaliar conhecimentos técnicos de candidatos à vagas na área de desenvolvimento de software. É bastante comum, no processo de seleção, enviarmos testes para desenvolvedores implementarem de forma remota seus testes e então, ao recebê-lo, entender como e porquê o candidato implementou o teste da maneira como fora implementado. Para esse caso o arquivo README é a chave.
Comentarios