Executando verificação de segurança...
20
gabrielbaiano
2 min de leitura ·

Utilidade publica sobre documentação e repositórios!

Utilidade publica sobre documentação e repositórios!

Nos últimos dias eu estava caçando projetos no GitHub para usar como referência.
Só que eu me deparei com um problema gigante: a maioria dos repositórios não tinha uma documentação decente.

Várias vezes eu abria um repositório e não fazia ideia do que ele era, para que servia ou como usar. Isso me fez perceber que uma boa documentação é tão importante quanto o código.

Veja por si só e compare a documentação desses dois projetos

Repositório 1

Repositório 2

Você consegue saber em uma primeira impressão, sobre oque é o primeiro repositorio e como usar ele de forma efetiva ?

O poder de um bom README

Um README bem feito transforma completamente a experiência de quem chega no seu repositório:

  • Explica o propósito: o que o projeto resolve
  • Demonstrar com imagem: se possivel
  • Mostra como usar: instalação, dependências, exemplos
  • Facilita contribuições: guia de issues, pull requests, padrões de código
  • Dá credibilidade: demonstra cuidado, organização e profissionalismo

E o mais importante: faz com que outras pessoas queiram usar e contribuir.

Pensando nisso eu fiz um Template de documentação

👉 https://github.com/GabrielBaiano/awesome-readme

Eu fiz ele pensando em conceitos gerais que a maioria dos projetos usam, você instala via NPM escolhe os as documentações que você precisa, depois é só editar as informações!

Mas você não precisa usar o meu, só o fato de você conseguir passar a mensagem sobre o repositório e criar seu próprio Awesome README.md já é um enorme passo para tornar seus projetos mais acessíveis.

text

Carregando publicação patrocinada...
2
1
1
3
1
1
2
gabrielbaiano
  • Autor
    Autor

Cara a documentação em projetos do github temos o Readme, a parte de contribuição, a lincença ( MIT, licença apache, etc ) e você pode linkar outras paginas .md do seu projeto no Readme.

Então se você pensa em fazer um projeto open source por exemplo, a parte de Contribuição (que é um arquivo que vai ficar destacado ao lado do readme principal junto com a licensa), é importortante para explicar e detalhar como a pessoa pode ou não contribuir e como ela vai fazer isso.

A licença é importante para definir o "conteito legal" do seu projeto, se ele pode ser copiado ou modificado, etc.

E customizar o seu link de issue é um toque bacana para colocar no seu projeto!

PS: Tem esses outros 2 arquivos que são destacados CODE_OF_CONDUCT.md e SECURITY.md que cada um tem sua função sobre issues e codigos de conduta.

Normalmente o pessoal preenche mais só o readme.md mesmo, mas é bom saber identificar as outras ocasiões aonde deve ter os outros arquivos. Mas tudo depende da complexidade do seu projeto ou se for open, se ele for MUITO complexo é normal eles tirarem a documentação do github e jogar para um site a parte (exemplo: documentação de bibliotecas grandes como Electron)