Documentação/guia boas práticas open source

[helderberto]

Olá, tudo bem?

Estou a alguns dias analisando qual a melhor ferramenta/plataforma, e padrões para criar documentações para empresas.

O porque disso, sempre que novos colaboradores ingressam na empresa que atuo, passamos pelo mesmo processo de treinamento, onde são repassadas as necessidades para com o colaborador e os diferenciais por ser um trabalho remoto.

Vou listar aqui as duas plataformas que mais chamaram atenção, ambas ficariam com arquivos públicos, porém são as que mais nos chamam atenção:

• Gitbooks: o principal fator que nos chamou atenção foi a navegação amigável e a facilidade em criar a documentação;
• Github: Repositório com as práticas da empresa.

Estamos abertos a sugestões tanto para plataforma, quanto para boas práticas na escrita da documentação.

O que você sugere?

[woliveiras]

Acho o GitBook algo muito bom de se usar, @helderburato!

Você pode tando deixar no gitbook.com, quanto criar um repositório seu e criar o GitBook a partir dali e servir em seu domínio (ex.: https://github.com/woliveiras/vimparanoobs > https://woliveiras.com.br/vimparanoobs).

A Wiki do GitHub é bem legal por si só, mas o GitBook é mais personalizável com você podendo adicionar seu CSS.

Não vejo nenhuma grande vantagem entre um e outro a não ser esse esquema de personalizar usando seus próprios estilos.

[ghost]

@helderburato documentação tem que ser organismo vivo, se não acaba ficando defasada. Se for algo unilateral e que depende de uma iniciativa só de uma pessoa fica bem complicado.

Para o que tu queres fazer primeiro teria que definir um bom workflow, por exemplo: quando documentaria o uso de um plugin ou ferramenta nova já que no processo de desenvolvimento você vai tá focado em resolver o problema?

O Gitbook já tive experiência e em um workflow bem definido fica muito simples você criar conteúdo pra ele. A disponibilidade dele também é bacana e tu pode deixar no gh-pages, deixar público e opensource para as pessoas também ajudar a evolui-lo.

Hoje atuar com Gitbook e Storybook vem sendo muito mais simples pra mim.

Porém se tu quiser um exemplo de projeto que usa o Github bem eu te indico conferir o da Zalando para criação de projetos opensource na organização.

Como o @woliveiras falou não existe o melhor, talvez o que tu tenhas mais que pensar é no workflow e como vai ser a manutenção disso.

[gabrieldarezzo]

Começa pelo básico...

Já rola um README.md em cada projeto explicando como fazer uma copia para Local / Rodar os testes / Deployment ?

Quais etapas antes do commit?
Qual padrão / PSR / codeStyle utilizar?
Ocorre CodeReview?
Qual o fluxo de um BugFix?
Qual o fluxo de uma nova feature?

Se tudo acima estiver bem definido e disponível aos novos devs já é um ótimo começo.

---

Uma ferramenta que conheci recentemente foi o husky
Ele basicamente facilita os hooks, ex:

• Ele pode obrigar todos os testes passarem
• CodeStyle ficar 100% antes de subir (prepush)

[TerraMichael]

Concordo, mano...

Estou criando um padrão de documentação técnica para minha squad e pensei exatamente isso... Começar pelo básico (readme.md), já que a squad hoje não possui um padrão e nem doc. técnica.

Estou fazendo o levantamento das definições básicas e buscando na internet algum modelo que possa ter coisas que eu não tenha previsto...

Bom comentário.

[helderberto]

@woliveiras gostei da sugestão, muito bacana a documentação que você criou, inclusive vou me basear para algumas coisas, obrigado pelo feedback!

---

@edmolima concordo com sua visão, neste caso estamos visando utilizar para processo de treinamento para novos integrantes da equipe, ou seja, é um processo que tende a mudar, mas focado nos processos de comunicação, atribuição de tarefas, e a metodologia de trabalho em si.

Caso eu não esteja sendo claro para com o objetivo, por favor, apenas me informar.

---

@gabrieldarezzo estas etapas iniciais, README.md no projeto já são aplicadas, porém gostaríamos de criar um material para consulta, e também para padronização sobre as metodologias de trabalho.

Ultimamente como estamos utilizando Node.js, react, e em praticamente todos os projetos a base está sendo javascript, utilizando o codeStyle airbnb validando o código utilizando git hooks antes de efetuar push verificando se os arquivos estão seguindo os padrões de código.

Em relação a novas features, costumamos criar novas branchs para cada feature, e antes de ser efetuado o merge na master, é efetuado o teste se a funcionalidade ficou de acordo com a necessidade do cliente.

Mas já que você abordou o assunto, como lida com essas situações de novas features e bugFix?

[afonsopacifer]

Para criar um projeto, eu cheguei a fazer uma checklist para não esquecer as coisas importantes:

https://afonsopacifer.github.io/open-source-checklist/

Uma boa dica, é clicar nos links de cada item da lista, pq ele aponta para um artigo ou video explicando como implementar o item :)

[gabrieldarezzo]

@helderburato

Faço o feijão com arroz tmb.
Master, HotFix na tag, e para nova features é criado uma branch.

[TerraMichael]

Seguindo a dica do gabriel aqui nos comentários, acredito que para aqueles que não possuem nada de documentão, o ideal primeiro é começar pelo básico como o readme.md.

Alguns links que possam ajudar:

Como escrever um README incrível no seu Github:
https://www.alura.com.br/artigos/escrever-bom-readme

Markdown: como trabalhar com essa linguagem de markup?
https://www.alura.com.br/artigos/como-trabalhar-com-markdown

Repo de exemplo:
https://github.com/facebook/docusaurus
https://github.com/nasa/openmct