Como documentar seu projeto backend

Documentar um projeto backend é uma tarefa primordial, principalmente para aqueles que desejam chamar a atenção de outros devs e até mesmo recrutadores para os seus projetos Backend.

Esse projeto tem o intuito de te direcionar à como montar uma boa documentação para seus projetos Backend, além de fornecer um modelo de exemplo para uso posteriormente.

Por que documentar?

Todo código público hospedado em um repositório do GitHub pode ser considerado open-source. Mais do que só um "repositório" pra guardar os seus códigos, o GitHub também é uma excelente ferramenta para descobrir novos projetos e conhecer novos devs, pois tudo que há de bom (e de ruim) está hospedado aqui.

Acontece que quando encontramos certos projetos no GitHub que não possuem uma documentação adequada, aquele projeto em questão deixa de ser interessante, justamente por apresentar certo "desleixo" quanto ao código criado, onde vem o seguinte sentimento na cabeça: "Se o dev não teve vontade de documentar o projeto, talvez ele não seja tão interessante assim", e acredito que isso não só me afasta, como também afasta possíveis recrutadores.

Sempre enxerge o README do seu projeto como se fosse uma explicação do mesmo pra qualquer outra pessoa, seja ela técnica ou não.

Documentar seu projeto traz algumas vantagens, sendo elas:

• Pra você:

  • Seu código terá mais credibilidade
  • Seu código será mais chamativo para contribuidores com o projeto
  • Recrutadores se apaixonarão pelo seu projeto.

• Para a comunidade open-source:

  • Podem facilmente contribuir com o projeto
  • Podem aprender algo novo com o seu projeto.

O que sua documentação deve ter?

O que é imprescindível

• Descrição breve do projeto
• Escrever sobre qual problema o seu projeto resolve.
• Instruções de instalação e execução
• Instruções sobre "como contribuir" com o projeto.
• Se seu projeto for uma API WEB, um documento listando cada um dos endpoints da aplicação (ou um link para uma fonte externa que contenha esses dados).

O que é "desejável" numa boa documentação

• Um desenho da arquitetura usada no projeto, com argumentos que defendam o desenho escolhido, além de uma explicação clara sobre ela.
• Um documento listando as principais features do projeto.
• Padrões de projetos adotados e o porquê de você usá-los.
• Style guide seguido no projeto e o porquê.
• Se o seu projeto for uma API WEB, um documento com exemplos de como consumí-la.
• Informações sobre o que você aprendeu com esse projeto.

Por onde começar?

Tá perdido e não sabe por onde começar a fazer seu README baseado nessas sugestões? Criamos um modelo para te ajudar, clique aqui