Documentação unificada | Unified documentation

[lguima]

Salve, pessoal!

Trazendo um assunto que comentei no Discord um tempo atrás sobre a unificação das documentações, em especial o Código de Conduta.

O @giuliocc comentou que o assunto já surgiu na 6ª Reunião das pessoas mantenedoras, mas não foi definido.

As ideias que surgiram seria um Código de Conduta a nível do Querido Diário, ou a nível OKBR, que poderia ser aplicado em qualquer instância (evento, projeto, plataforma).

O que acham? Veem alguma outra documentação que poderíamos considerar unificar?

cc: @rennerocha

---

[English]

Hi there!

Bringing here what I commented on Discord a while ago about a unified documentation, especially for the Code of Conduct.

@giuliocc mentioned that the matter already came up at the 6ª Maintainers meeting but it wasn't defined.

The ideas that came up are: a Code of Condutct in the Querido Diário level, or in the OKBR level, which could be applied to any instance (evens, project, platform).

What you think? You see any other documentation that we could consider unifying as well?

[ogecece]

@lguima ótimo ponto! O Código de Conduta que você editou para este repo poderia ser utilizado a nível de OKBR sim. Está muito bom e é o que temos utilizado também no Discord.

O caminho para isso seria criar um repositório .github na organização? Estou um pouco por fora de como poderia ser feito.

Sobre outras documentações, acredito que o Guia de Contribuição deste repositório central de comunidade se estende a todo o QD pois são linhas mais gerais. Enxergo que cada repositório tem também seu próprio guia de contribuição com indicações específicas mas deixando uma referência para o guia mais geral.

O que acha?

---

English

@lguima great point! The Code of Conduct you edited for this repo could be used at OKBR level. It's very good and it's what we've also been using on Discord.

Would the way to do that creating a .github repository in the organization? I'm not up to date in that regard.

Regarding other documentation, I believe that the Contribution Guide of this central community repository extends to the entire QD as it is more general. I see that each repository also has its own contribution guide with specific indications but also pointing to the more general guide.

What do you think?

[lguima]

Sobre o Código de Conduta, é uma alternativa manter no GitHub, mas eu diria que não é a mais acessível para reutilizar fora dessa rede.

Talvez colocar no site da OKBR seja uma melhor opção, assim como fez a Codamos:

• https://www.codamos.club/codigo-de-conduta

Quanto ao Guia de Contribuição, concordo também que o que existe hoje aqui pode ser reutilizado/referenciado.

---

[English]

Regarding to the Code of Conduct is an alternative to keep it in GitHub, but I would say is not the most accessible to reuse outside this network.

Maybe placing it in the OKBR website is a better option, as well as Codamos did:

• https://www.codamos.club/codigo-de-conduta

About the Contribution Guide, I agree that the existing one can be reused/referenced.

[trevineju]

Olá!

Muito bom ter começado isso, @lguima! Seguindo em frente com essa ideia, comecei a buscar a padronização dos repositórios usando o que foi feito no querido-diario-comunidade como referência. Mencionei isso na issue #14, mas gostaria de trazer esta discussão pra cá, onde deveria estar e deixo a issue em espera um pouco.

O padrão de documentação pensado, tendo em vista uerido-diario-comunidade, o complemento trazido por @giuliocc, a correção acrescentada na issue e outras trocas em comunidade foi:

Na raiz do repositório conter:

• README.md;
• LICENSE.md; arquivo de mesmo conteúdo em todos os repositórios
• Diretório .github

No diretório .github conter:

• CODE_OF_CONDUCT.md e suas traduções; deve apontar para CODE_OF_CONDUCT.md de comunidade
• CONTRIBUTING.md e suas traduções; deve apontar para CONTRIBUTING.md de comunidade e conter especificações do repositório
• FUNDING.yml; arquivo de mesmo conteúdo em todos os repositórios
• SUPPORT.md e suas traduções; arquivo de mesmo conteúdo em todos os repositórios
• E as traduções do README.md daquele repositório

O que vocês acham dessa proposta?

Assim que terminar essa revisão global em nível de diretórios e arquivos, penso em padronizar os arquivos internamente (README.md e CONTRIBUTING.md), já que cada repositório tem seus próprios detalhes, mas que teriam seções essenciais que são comuns também. Vocês teriam ideias quanto a isso que poderíamos já ir levando em conta?

---

[English]
Hi!

Great to have started this, @lguima! Moving forward with this idea, I started looking for the standardization of repositories using what was done in the querido-diario-comunidade as a reference. I mentioned this in issue #14, but I would like to bring this discussion here where it should be and put the issue on hold for a bit.

In view of what was done in the querido-diario-comunidade, the complement brought by @giuliocc, the correction added in the issue and other talks in the community was, the standard proposed is:

In the root of the repository contain:

• README.md;
• LICENSE.md; file with same content in all repositories
• .github directory

In the .github directory:

• CODE_OF_CONDUCT.md and its translations; should point to community CODE_OF_CONDUCT.md
• CONTRIBUTING.md and its translations; should point to community CONTRIBUTING.md and contain repository specs
• FUNDING.yml; file with same content in all repositories
• SUPPORT.md and its translations; file with same content in all repositories
• And the README.md translations from that repository

What do you think of this proposal?

Once I'm done with this global directory and file-level review, I'm thinking about standardizing the files internally (README.md and CONTRIBUTING.md), as each repository has its own details, but would have essential sections that are common as well. Do you have any ideas about this that we could take into account?

[lguima]

Oi, @trevineju!

Boa, essa era a proposta mesmo, todos itens fazem sentido pra mim.

Sobre a estrutura do README o que tinha pensado seria replicar o que tem aqui em -comunidade e adicionar seções que forem pertinentes a cada repositório:

• Título
• Contribuição
• Querido Diário (ecossistema)
• Open Knowledge Brasil
• Licença

E quanto ao CONTRIBUTING, imagino que apontar para a comunidade e incluir o que for específico do repositório.

---

[English]

Hi, @trevineju!

Great, that was the idea, all items make sense to me.

Related to the README structure what I've thought was to duplicate what it's here in -comunidade and add the sections relevant to each repository:

• Title
• Contributing
• Querido Diário (ecosystem)
• Open Knowledge Brasil
• Licence

And about to CONTRIBUTING, I imagine pointing to the -comunidade and include what is repository specific.

[lguima]

@trevineju reparei agora, a gente removeu a lista de repositórios relacionados (Querido Diário [ecossistema]), foi proposital?

[trevineju]

Foi. Mencionei isso na mensagem logo abaixo na thread. Foi porque a lista já está em CONTRIBUTING.md de comunidade e não vi porque ficar replicando a mesma lista em vários README.md (inclusive pela questão de manutenção). A partir dos README se chega na lista de duas formas:

1. README.md > "Dentro do ecossistema do Querido Diário, este repositório......" > CONTRIBUTING.md de -comunidade
2. README.md > "Você encontra como fazê-lo no CONTRIBUTING.md > CONTRIBUTING.md do repositório > "Leia o Guia de Contribuição!" > CONTRIBUTING.md de -comunidade

por eu ainda não ter mexido no contributing dos repositórios, o hiperlink do (2) ainda não existe, mas existirá. Está no padrão para o contribuitng.md que mostrei aqui na thread.

[lguima]

Ah, sim, verdade, é que eu tinha colocado pensando em uma pessoa que chega por qualquer repositório, pois indicaram, ela achou em alguma pesquisa e se interessou pela proposta do projeto, mas não é a área dela, por exemplo, alguém de backend que chega no repositório de frontend. Com a descrição do ecossistema ela veria facilmente a amplitude do projeto e que tem outras frentes que ela pode atuar. O CONTRIBUTING.md assume-se que serão especificidades do repositório, seria um passo a mais pra pessoa encontrar a informação.

[trevineju]

Olá, pessoal! Seguindo com as propostas, está abaixo o que penso que deveria ter em todos os READMEs. Ele engloba o padrão do @lguima, algumas demandas apontadas na issue okfn-brasil/querido-diario#608 e itens extras frutos de leituras.

- Badge de "doe"
- Imagem do projeto

# Título do Repositório
- Apresenta a fase e o objetivo daquele repositório dentro do escopo do projeto completo

# Sumário
- Lista de tópicos do README

# Contribua
- Badge do Discord
- Direciona leitura para CONTRIBUTING.md

# Como executar
- Lista linguagens/ferramentas utilizadas (com hiperlinks às suas documentações) ou aponta para onde achá-las dentro do repositório
    - Mostra os comandos de instalação delas
- Lista dependências necessárias ou aponta para onde achá-las dentro do repositório
    - Mostra os comandos de instalação delas
- Mostra os comandos de execução do projeto com exemplos em 3 sistemas operacionais (Linux, MacOS e Windows)
- Aponta para FAQ de configuração

# Agradecimentos
- Menciona a OKBR, a comunidade técnica, as pessoas embaixadoras, os doadores financeiros, universidades e empresas. Aponta para a página de apoio do projeto para verem a lista completa.

# Open Knowledge Brasil
- Badges de redes sociais
- Parágrafo sobre a missão da OKBR (hiperlink pro site)

# Licença
- Aponta para LICENSE.md 

Os badges são criados com https://shields.io/;
O sumário e os exemplos de comandos de instalação de pré-requisitos e dependências são itens demandados na issue indicada;
Do esquema que @lguima sugeriu, adicionei a seção de agradecimentos (tem no repositório do frontend do QD e está muito bacana) e não inclui a lista de ecossistema de repositórios por ela já estar presente no CONTRIBUTING e o README leva até ele.
A "FAQ de configuração" é uma ideia de abrir uma Discussion para problemas de instalação, execução ou configuração do ambiente. O repositório do querido-diario (de raspadores) tem um trecho de solução de problemas no README, mas pensei que deixar lá fica muito engessado e depende de mantenedoras atualizarem. Se for uma Discussion, pode ter vida própria de gente pedindo ajuda e outras solucionando e ficando registrado para ajudar outras pessoas.

---

[ENGLISH]

Hello! Continuing with the proposals, below is what I think should be in all READMEs. It covers the @lguima standard, some demands pointed out in the issue okfn-brasil/querido-diario#608 and extra items resulting from readings.

- Badge of "donate"
- Project image

# Title of Repository
- Presents the phase and objective of that repository within the scope of the complete project

# Summary
- List of README topics

# contribute
- Discord Badge
- Directs reading to CONTRIBUTING.md

# How to run
- Lists languages/tools used (with hyperlinks to their documentation) or points to where to find them within the repository
    - Shows their installation commands
- List required dependencies or point to where to find them within the repository
    - Shows their installation commands
- Shows the project execution commands with examples in 3 operating systems (Linux, MacOS and Windows)
- Points to configuration FAQ

# Thanks
- Mention OKBR, the technical community, ambassadors, financial donors, universities and companies. Point to the project's support page for the full list.

# Open Knowledge Brazil
- Social media badges
- Paragraph about OKBR's mission (hyperlink to website)

# License
- Points to LICENSE.md

Badges are created with https://shields.io/;
The summary and examples of prerequisites and dependencies installation commands are demanded items in the indicated issue;
From the schema @lguima suggested, I added the acknowledgments section (it's in the QD frontend repository and it's very cool) and it doesn't include the list of repositories ecosystem because it is already present in CONTRIBUTING and the README for it.
The "Configuration FAQ" is an idea to open a Discussion for problems installing, running or configuring the environment. The querido-diario repository (of scrapers) has a troubleshooting snippet in the README, but I thought leaving it there is too stale and depends on the maintainers to update it. If it's a Discussion, it can have a life of its own with people asking for help and others solving and getting registered to help other people later.

[trevineju]

Já os CONTRIBUTINGs, poderiam ter essa cara:

- Badge do Discord

# Contribuindo

Antes de mais nada... Leia o [Guia para Contribuição](link) do Querido DIário. Este guia traz informações gerais, como nosso código-de-conduta, a lista de repositórios do projeto e as primeiras ações para você tomar.

Já leu? Então vamos às especificidades do repositório [nome]:

## Especificidades
- Informa sobre labels específicas sendo usadas no repositório
- Menciona que toda contribuição é válida, mas as de especial interesse são aquelas que nos ajudam a atingir as [milestones]
- Reforça que uma issue de sinalização é necessária quando a pessoa decidir onde vai contribuir 
- E se a contribuição ainda estiver no âmbito de amadurecimento, proposta de mudanças, reflexões ou ideias, direcionar para Discussions. 

## Desafios
- Menciona possibilidades de contribuição no repositório
- Indica documentações ou tutoriais para formação dentro dessas possibilidades

# Mantendo

As pessoas mantenedoras devem seguir as diretrizes do [Guia para Mantenedoras](link) do Querido Diário. Além disso, para este repositório também devem se atentar à:  

- Lista itens de atenção mínimos ao se avaliar um PR

No caso do README, acho que o modelo é possível de implementar em todos os repositórios. Já o CONTRIBUTING, acho que tem repositório que não terá alguns tópicos. Fiz a lista pensando em um caso completo, o que seria uma cobertura "máxima"

---

[ENGLISH]

CONTRIBUTINGs, on the other hand, could look like this:

- Discord Badge

# contributing

First of all... Read the [Guide to Contribution](link) of Querido DIário. This guide provides general information such as our code-of-conduct, the project's list of repositories, and the first steps you can take.

Already read? So let's get to the specifics of the repository [name]:

## Specificities
- Informs about specific labels being used in the repository
- Mention that every contribution is valid, but those of special interest are those that help us reach the [milestones]
- Reinforces that a flag issue is needed when the person decides where to contribute
- And if the contribution is still in the scope of maturation, proposal of changes, reflections or ideas, direct to Discussions.

## Challenges
- Mentions contribution possibilities in the repository
- Indicates documentation or tutorials for training within these possibilities

# Mainteining

Mainteiners should follow the guidelines in Querido DIário [Guide for Mainteiners](link). In addition, for this repository you should also pay attention to:

- Lists minimum attention items when evaluating a PR

In the case of README, I think the model is possible to implement in all repositories. As for CONTRIBUTING, I think it has a repository that will not have some topics. I made the list thinking of a complete case, what would be a "maximum" coverage

[lguima]

Oi, @trevineju! Valeu por dar continuidade, curti demais a organização da proposta!

Único detalhe sobre os troubleshootings é que talvez usar a Wiki do GitHub possa ser mais eficiente que uma Discussion, assim qualquer pessoa pode contribuir com a descrição da solução.

[trevineju]

A sugestão pelo Discussions era mais que para alguém enviar uma resposta não depende de aprovação de mantenedora, como mesmo os PRs para wiki dependeriam.

[lguima]

A Wiki, até onde eu lembro, não precisa de aprovação não.

[ogecece]

Minha opinião sobre essa parte:

• Pedidos de ajuda -> lista de discussões (discord)
• Problemas -> issues
• Problemas comuns -> documentação

Não entendi muito bem o problema de ter que fazer um PR pra modificar a documentação do repo. Pra mim esses problemas comuns ficariam na documentação do repo mesmo (talvez poderia até ser um arquivo diferente do README pra não poluir muito, mas o README apontar pra ele).

[lguima]

A Wiki é por repositório e dá bastante opção pra organizar em páginas e tem um editor mais amigável.

Referência:

• https://docs.github.com/en/communities/documenting-your-project-with-wikis

[ogecece]

Então @lguima mas o problema de documentação na wiki é que não dá pra fazer PR. Ou deixaria aberto pra qualquer pessoa poder editar ou ficaria apenas na equipe de manutenção. Acredito que deixar na documentação do próprio repo seja melhor pois qualquer pessoa pode fazer PR e o crivo do que será adicionado ou não à documentação continua sendo da equipe de manutenção