O projeto Linux Foundation

Esta página contém os detalhes de um projeto de redação técnica aceito para a Google Season of Docs.

Resumo do projeto

Organização de código aberto:
The Linux Foundation
Redator técnico:
jaskiratsingh2000
Nome do projeto:
CHAOSS: Create a CHAOSS Community-wide Handbook
Duração do projeto:
Duração padrão (três meses)

Project description

RESUMO DO PROJETO:

Atualmente, os grupos de trabalho da comunidade CHAOSS desenvolveram as próprias maneiras de trabalhar e documentaram processos diferentes em vários graus. Os grupos de trabalho incluem grupos de trabalho com métricas comuns, WG de diversidade e inclusão, evolução, risco e valor, que estabeleceram suas próprias formas de participação e trabalho e adaptaram diferentes formas de comunicação e cultura de trabalho. Esses grupos de trabalho, de acordo com as métricas, têm áreas de foco e origens diferentes, o que funciona para métricas adequadas, lideram várias pesquisas e desenvolvimentos na categoria dos grupos de trabalho e sabem o caminho certo para liderar várias pesquisas e desenvolvimentos nas respectivas categorias, mas os processos para os recém-chegados e colaboradores atuais podem não saber como participar ou seguir o caminho certo para os respectivos trabalhos.

Por isso, as coisas na comunidade CHAOSS não são padronizadas. Portanto, para conhecer o processo certo e os fundamentos básicos da cultura de trabalho em toda a comunidade, o objetivo do manual da comunidade é centralizar informações importantes e padronizar partes delas no projeto CHAOSS. As informações importantes e as partes de padronização se concentram principalmente nos processos que a CHAOSS usa para que ela tenha um acordo sobre como a comunidade realiza o trabalho, como os novatos podem participar e seguir os fundamentos da comunidade e quais processos e caminhos os novatos ou membros atuais precisam seguir para aproveitar a liderança na comunidade da CHAOSS.

O manual deve servir como um manual de instruções para os membros atuais e novos da comunidade sobre como trabalhar no projeto CHAOSS. Esse projeto envolve um componente criativo de coleta e organização de conteúdo para o manual, bem como um componente técnico de definição de como representar o manual.

QUAL É A NECESSIDADE DISSO?

O Manual da comunidade é um documento que define as principais políticas e procedimentos e descreve a missão, os valores e o funcionamento da comunidade.

Este manual fornece uma introdução e explicações claras para os membros recém-chegados à comunidade. No momento, o Manual da comunidade CHAOSS está disponível no repositório do GitHub e precisa ser reformulado e reestruturado com mais informações para os novos usuários e os usuários atuais da comunidade. Por isso, este manual da comunidade CHAOSS vai ajudar novos membros e membros da comunidade das seguintes maneiras:

  • Formalizar e organizar as políticas da comunidade CHAOSS, reunindo todas em um só lugar
  • Comunicação da introdução, missão, visão e liderança da comunidade
  • Entender as práticas da comunidade CHAOSS
  • Diretrizes de colaboração
  • Como definir os fluxos de trabalho do projeto
  • Como funciona a cultura da comunidade CHAOSS
  • Perguntas frequentes gerais
  • Orientação individual

DESCRIPTION OF THE PROJECT:

O manual da comunidade será dividido em várias "seções", que vão conter informações adequadas e detalhadas sobre determinados tópicos. As seções podem ser divididas das seguintes maneiras:

  • Introdução
  • A comunidade CHAOSS faz isso
  • Caminho para a liderança
  • Terminologia
  • Diretrizes de colaboração
    • Desenvolvedor
    • Designer
    • Editor
    • Profissional de marketing
  • Métricas
  • CHAOSScon
  • CHAOSScast
  • Vídeos de reuniões
  • Perguntas frequentes gerais
  • Orientação individual
    • Google Summer of Code
    • Outreachy
    • Season of Docs do Google

ENTREGAS DETALHADAS DO PROJETO

1.) Introdução:

Esta seção vai funcionar como a primeira página do manual da comunidade CHAOSS e vai abordar os detalhes, a visão geral e o uso do manual. Confira abaixo:

A.) Ele vai conter a mensagem de boas-vindas com uma breve descrição da comunidade CHAOSS, que ajudaria a convencer os leitores a ler o manual. Também vou incluir a colagem de imagens tiradas aqui https://chaoss.community/chaoss-photo-album/, que destaca os vários movimentos na comunidade. B.) A página também conterá os detalhes sobre todas as seções, com uma descrição de linha explicando cada seção e os links apropriados. C.) Uso do Manual: o uso do manual já existe aqui( shorturl.at/cqQU6 ), mas revisarei o uso do Manual com uma marcação melhor, que incluirá o Fluxo do Manual(incluirei como as coisas acontecem quando alguém quer adicionar, remover ou discutir as coisas relacionadas ao manual. Ele pode acompanhar o processo de comunicação para qualquer coisa relacionada ao manual.), Diretrizes do manual(que incluem seu uso dentro da comunidade e escopo), contribuição para o manual ( que inclui como usar o repositório para fazer alterações, criar RPs, modelo a seguir para fazer alterações no manual e no Guia de estilo) e compartilhar feedback sobre o manual. No compartilhamento de feedback, vou incluir um modelo e diferentes maneiras de os usuários acompanharem o processo para fornecer ou usar problemas do GitLab.

2.) A maneira da comunidade CHAOSS:

O modo de trabalho da comunidade CHAOSS será importante para que as pessoas entendam as práticas e diretrizes da comunidade. O Workflows poderia dar mais ênfase a ela e delinear as práticas da comunidade da melhor maneira. Esta seção inclui:

A.) Valores gerais: descrevem como a sustentabilidade, a abertura e a transparência são tratadas na comunidade CHAOSS. Vou explicar esses valores para que os novos usuários ou os atuais os entendam e os levem em consideração ao trabalhar com a comunidade. B.) Diretrizes da comunidade: inclui como se envolver na comunidade CHAOSS e seguir os termos básicos. Isso também explica a cultura de trabalho seguida na comunidade. (o que fazer e o que não fazer). Ele vai incluir a lista de verificação principal de colaboradores/mantenedores, além de informar aos outros como trabalhar com os mantenedores e quais são as listas de verificação. C.) Grupos de trabalho: esta página( https://chaoss.community/participate/ ) contém informações sobre os grupos de trabalho, como a descrição do WG, o link do Repo e informações sobre as reuniões. No manual, vou incluir como participar dos diferentes grupos de trabalho e entender o processo de avaliação das métricas, entender a cultura de trabalho do respectivo WG e como se tornar o principal colaborador de diferentes grupos de trabalho.

3.) Caminho para a liderança:

No entanto, ganhar liderança em um projeto de código aberto pode ser vital para o sucesso de uma comunidade no mundo comercial. Portanto, levando isso em consideração, vou incluir o seguinte:

A.) Liderança técnica: isso inclui os processos e as responsabilidades dos mantenedores do repositório, do redator de documentação e do mantenedor do site. Liderança de governança: inclui os caminhos para membros do conselho e tomadores de decisão C.) Liderança operacional: contém o caminho para gerentes de comunidade

4.) Terminologia:

A terminologia ajudaria a descrever os termos e os itens que são usados com frequência na comunidade CHAOSS. Além disso, também vou incluir as diretrizes de uso da terminologia, como maiúsculas, abreviações e palavras a serem evitadas, com os motivos. Os termos que serão incluídos são Projeto CHAOSS, Saúde da comunidade de código aberto, Análise de código, Grupo de trabalho, Métrica de software de código aberto, Métrica comum, Métrica de diversidade e inclusão, Grupo de trabalho de evolução, Grupo de trabalho de risco, Grupo de trabalho de valor, Lançamento de métrica, Área de foco.

5.) Diretrizes de contribuição:

Esse é o principal contexto de qualquer comunidade de código aberto, já que a maioria delas depende das contribuições ou do trabalho voluntário. Isso ajuda qualquer usuário/novo participante a entender as necessidades básicas e as diretrizes que precisam seguir. Isso inclui os seguintes detalhes:

A.) Como entender o cronograma da comunidade: este tópico vai apresentar um panorama do cronograma da comunidade CHAOSS, que ajudará os usuários a saber qual caminho ou processo seguir, prioridades aos vários trabalhos no projeto CHAOSS. B.) Explicação das coisas necessárias para fazer qualquer contribuição prática, como desenvolvimento, documentação, design, teste etc. C.) Oferecer uma breve visão geral do funcionamento do GitLab D.) Guia de revisores/mantenedores

Essa seção também vai conter os "Papéis e responsabilidades" para cada categoria de contribuição, que são os seguintes:

a.) DESIGN: esta subseção incluirá o "CHAOSS Design Work Flow" e as diretrizes de design, que conterão os princípios de design, o processo e as ferramentas usadas que os colaboradores precisam seguir ao contribuir para o campo de design. b.) DESENVOLVIMENTO: contém o guia para a contribuição à base de código. Ele contém os requisitos técnicos, a estrutura do projeto, a configuração do projeto(Augur, Cregit, GremoireLab). DOCUMENTAÇÃO: inclui recursos para documentação, incluindo ferramentas e guia de estilo. d.) EXTENSÃO: isso inclui como os colaboradores podem apoiar a comunidade CHAOSS no crescimento da divulgação, como escrever blogs, usar identificadores sociais, organizar reuniões e eventos.

6.) Métricas

Atualmente, o site da comunidade CHAOSS contém as informações das versões de métricas( https://chaoss.community/metrics/ ). É mais importante que as pessoas entendam como seguir o processo para disponibilizar o site de métricas nesse site. Portanto, esta seção guiará as informações que ajudarão os usuários a conhecer os processos e trabalhar para ter sua própria versão de métrica.

7.) CHAOSScon:

As informações sobre o CHAOSScon já existem no GitHub( https://github.com/chaoss/governance/blob/master/community-handbook/chaosscon.md) e no site( https://chaoss.community/CHAOSScon-2020-NA/ ), mas faz mais sentido adicionar os detalhes e as informações que explicam os processos e as formas de gerenciamento do Handbook.con no O manual vai conter as seguintes informações:

A.) Detalhes sobre o comitê organizador: explica os processos de como participar do comitê organizador do CHAOSScon B.) Gerenciamento do processo de chamada para apresentação de propostas: isso inclui gerenciar o registro de autores, enviar propostas e documentação, revisão e processo de aprovação. C.) Gerenciamento e publicação do programa CHAOSScon D.) Como gerenciar os itens de publicidade e marketing E.) Como lidar com propostas de patrocínio e fundos, incluindo pacotes

8.) CHAOSScast:

As informações do CHAOSScast estão disponíveis aqui: https://github.com/chaoss/governance/blob/master/community-handbook/chaosscast.md e serão incluídas no Manual com alguns detalhes adicionais, como participação, comitê de organização, publicidade e materiais de marketing.

9.) Vídeos de reuniões:

Ele vai conter todos os vídeos da reunião e a descrição, como participantes, agenda etc. que aconteceram no passado e estão disponíveis no YouTube.

10.) Perguntas frequentes gerais:

Elas vão conter as perguntas gerais comuns feitas na comunidade, o que ajudará os novatos e os membros da comunidade a responder algumas delas.

11.) Google Summer of Code:

Esta seção contém informações sobre o Google Summer of Code, os Critérios de qualificação e informações sobre como as pessoas podem participar da comunidade CHAOSS no Google Summer of Code. Essa seção também vai conter o modelo de proposta que as pessoas podem usar para elaborar a proposta e as funções e responsabilidades. Além disso, ele também vai conter informações que ajudarão os membros da comunidade a aprender o processo de se tornar administrador e mentor da organização.

  1. Outreachy:

Esta seção contém informações sobre o Outreachy, os critérios de qualificação e como as pessoas podem participar da comunidade CHAOSS no Outreachy.Ela inclui as funções e responsabilidades, incluindo o processo de se tornar o administrador e os mentores da organização.

  1. Season of Docs do Google:

Esta seção contém informações sobre o GSoD, os critérios de qualificação e como as pessoas podem participar da comunidade CHAOSS no GSoD. Ela inclui as funções e responsabilidades, incluindo o processo de se tornar o administrador e mentor da organização.

RESULTADO esperado DO PROJETO:

Os manuais desempenham um papel importante em qualquer comunidade. Da mesma forma, este manual da comunidade CHAOSS vai resultar em uma documentação mais organizada e detalhada para a comunidade. Seria fácil para qualquer novato que se juntar à comunidade, bem como para os membros atuais, entender os fundamentos e o funcionamento da comunidade CHAOSS. Além disso, este manual vai resultar em vários processos e caminhos para diferentes culturas de trabalho na comunidade CHAOSS.

DETALHES TÉCNICOS:

Proponho o uso da plataforma Gitbook para manter o manual, porque é um projeto colaborativo e fácil de usar para que as equipes trabalhem de forma mais eficaz e eficiente. Alguns recursos da plataforma GitBook:

  • WYSIWYG: um editor de texto poderoso e bonito
  • Markdown: suporte avançado e produtivo de atalhos de markdowns
  • Incorporação avançada: incorpora conteúdo externo da Web, como vídeos, snippets de código, artigos, músicas e muito mais
  • Painéis para redatores: tenha um painel inteligente para redatores com suporte à edição visual
  • Rascunhos: elabore novas mudanças e colabore de forma assíncrona
  • Comentários de suporte: discutir e revisar mudanças de rascunho
  • Rastrear o histórico de escrita: acompanhe tudo. Analisar e reverter mudanças
  • Insights: também oferece suporte a insights que acompanham o tráfego, a classificação e a qualidade do conteúdo
  • GitHub Sync: manter o fluxo de trabalho e sincronizar os documentos com o GitHub
  • Personalização da marca: domínios personalizados, logotipos personalizados, fontes, cores, temas, cabeçalhos etc.

Aqui estão algumas imagens que mostram a plataforma

  • shorturl.at/GNQR4
  • shorturl.at/gATZ8
  • shorturl.at/qrE57
  • shorturl.at/rFRX6
  • shorturl.at/eyLW1
  • shorturl.at/rwHS8

-- Onde o Manual será hospedado?

O Manual será hospedado no próprio GitBook, onde o GitHub oferece um mecanismo adequado para domínios personalizados, erros comuns e SEO.

Domínios personalizados: se a comunidade CHAOSS quiser hospedar o conteúdo no domínio personalizado, ele vai aparecer como docs.chaoss.community. A organização precisa criar qualquer subdomínio que quiser. Para configurar o domínio da organização, acesse as configurações da organização na plataforma Gitbook. Exemplo de imagem: shorturl.at/GNQR4

Os espaços do GitBook são veiculados pela nossa própria CDN com HTTPS ativado por padrão. Os certificados são emitidos pelo LetsEncrypt

Domínios compatíveis:

  • Subdomínio: www.example.com
  • Domínio personalizado: docs.example.com

-- Como sincronizar o Gitbook com o GitHub para que a edição possa ser feita nas duas plataformas de forma eficaz?

A integração com o GitHub é muito fácil de usar: se alguém mudar algum conteúdo no GitBook, as edições serão enviadas para um repositório do GitHub. Por outro lado, as confirmações enviadas para um repositório do GitHub são importadas no GitBook.

Configurar a integração do GitHub:

  • No seu espaço na plataforma do GitBook, clique na guia "Integrações" > GitHub.
  • Autorizar o acesso do GitBook à conta do GitHub vinculada à organização
  • Acesse o GitHub da sua organização e crie um repositório para o "Manual", por exemplo, "chaoss-handbook".
  • Agora selecione o repositório "chaoss-handbook" que você quer conectar usando a opção de autorização na plataforma GitBook.

Depois que essas etapas forem concluídas, o GitBook adicionará um webhook ao repositório do manual do caoss que permitirá buscar o conteúdo em cada alteração no repositório. Ao fazer mudanças no GitBook, um novo comentário será enviado.

Pronto. Qualquer pessoa pode continuar editando no repositório do GitBook ou do GitHub.

-- Como editar páginas na plataforma do GitBook?

Qualquer pessoa que queira editar algo na plataforma do GitBook precisa se inscrever com um link de convite ou de participação. O GitBook oferece suporte à edição visual, em que os usuários podem escrever diretamente nas páginas.

Um rascunho é uma versão editável do conteúdo do usuário que só pode ser acessada pelos autores e é criada automaticamente quando você começa a escrever (primeira letra no editor, criação de uma nova página, envio de uma imagem etc.).

As alterações feitas em um rascunho são próprias para ele, o que permite que os usuários contribuam no mesmo documento com outros membros simultaneamente sem criar conflitos. Isso é o que chamamos de edição assíncrona e resolução de conflitos.

A primeira versão do rascunho nem sempre está pronta para ser publicada imediatamente. Use ""salvar"" quando quiser continuar seu trabalho mais tarde ou se seu conteúdo ainda não estiver pronto para ser "mesclado".

Quando terminar de editar, você pode ""mesclar"" seu rascunho. O conteúdo que você escreveu ou as mudanças que você fez vão ficar disponíveis para os membros da equipe e/ou serão públicas.

Exemplos de imagem: shorturl.at/gATZ8 e shorturl.at/qrE57

-- Estrutura do conteúdo:

Sumário: cada espaço pode conter quantas páginas forem necessárias para escrever a documentação. Todas essas páginas estão visíveis no lado esquerdo da tela, no que chamamos de "Sumário". No sumário, você pode gerenciar suas páginas: criar novas páginas, grupo de páginas, adicionar links externos, adicionar uma variante, importar documentos externos, como sites ou arquivos, que são Markdown (.md ou .markdown), HTML (.html) e Microsoft Word (.docx).

Página inicial: é a página principal ou raiz da documentação e funciona basicamente como a página principal de todas as páginas da documentação. Como é a entrada principal da sua documentação e do seu espaço, essa página não pode ser movida, excluída, ter páginas filhas ou estar em um grupo.

Páginas: uma página tem um título e uma descrição opcional na parte de cima do editor. Você pode escrever e adicionar qualquer tipo de conteúdo a ela.Você pode aninhar páginas arrastando e soltando uma página abaixo de outra. Os elementos filhos de uma página serão ocultos, mas poderão ser recolhidos.

Links externos: essas entradas são links externos e não têm nenhum conteúdo no editor. A principal função deles é criar links para sites externos.

Variantes: você pode criar um conteúdo alternativo para sua documentação criando uma variante. Isso pode ser útil para documentar várias versões de uma API, uma biblioteca ou traduções.

Exemplo de imagem: shorturl.at/eyLW1 e shorturl.at/rFRX6

-- Como o Manual será apresentado no lado do cliente?

O manual da comunidade Chaoss será acessível com um subdomínio, que pode ser https://docs.chaoss.community, e terá a seguinte aparência para o usuário:

  • Manual do Mattermost: https://handbook.mattermost.com/
  • Docs da ponte da comunidade da Linux Foundation: https://docs.linuxfoundation.org/docs/ e muitos outros.

CRONOGRAMA DO PROJETO:

1.) Fase de integração da comunidade (17 de agosto a 13 de setembro)

A.) Semanas 1 a 4:

  • Discutir o projeto com mentores
  • Pesquise e colete as informações necessárias para as várias seções do projeto, faça perguntas para esclarecer dúvidas à comunidade
  • Esclarecer com a comunidade qual plataforma usar para o manual (sugiro o GitBook) e configurá-lo
  • Contribuir com problemas nos documentos

2.) Fase de desenvolvimento do documento (14 de setembro a 30 de novembro)

A.) Semana 5 (14 a 20 de setembro)

  • Seção de introdução do "Draft"

B.) Semana 6 (21 a 27 de setembro)

  • Rascunho da seção "A comunidade CHAOSS"

C.) Semana 7 (28 de setembro a 4 de outubro)

  • Redigir a seção "Caminho para a liderança"
  • Escreva a seção "Terminologia"

D.) Semana 8 (5 a 11 de outubro)

  • Elaborar o roteiro da comunidade
  • Rascunhos de diretrizes para contribuição de design

E.) Semana 9 (12 a 18 de outubro)

  • Seção "Desenvolvimento de rascunho"

F.) Semana 10 (19 a 25 de outubro)

  • Diretrizes da seção "Redação e contato"

G.) Semana 11 (26 de outubro a 1º de novembro)

  • Seção "Métricas de rascunho"
  • Rascunho da seção do CHAOSScon

H.) Semana 12 (2 a 8 de novembro)

  • Projetar a seção "Reunião"

  • Crie um rascunho de perguntas frequentes gerais da comunidade

    I.) Semana 13 (9 a 15 de novembro)

  • Rascunho sobre as diretrizes do GSoC

J.) Semana 14 (16 a 22 de novembro)

  • Rascunho sobre as diretrizes de contato

K.) Semana 15 (23 a 29 de novembro)

  • Intervalo: aperfeiçoamento e melhoria de todos os documentos

3.) Fase de avaliação (30 de novembro a 5 de dezembro)

A.) Semana 16:

  • Elaborar um relatório de projeto
  • Preencher a avaliação do projeto

INTERAÇÕES NA COMUNIDADE

1.) Envolvimento e discussões com a comunidade.

Bem, eu tenho navegado pela comunidade CHAOSS desde abril de 2020 e participado de várias discussões com membros da comunidade e com meus mentores de projeto específicos( Georg Link e Armstrong Foundjem). Uma dessas discussões que despertou maior interesse dos membros da comunidade foi “Propor o Gitbook como uma plataforma para hospedar o manual da comunidade” e pode ser encontrada na conversa da lista de e-mails do arquivo CHAOSS com o nome “Proposing Gitbook” como plataforma para hospedar o manual da comunidade. Também participei das ligações semanais da comunidade, o que me ajudou a dar atualizações para a comunidade.

2.) Como você coletará as informações necessárias para este projeto?

Como este projeto requer a elaboração de um manual para toda a comunidade, para que as informações que precisam ser acessadas nele sejam coletadas e discutidas com os membros da comunidade. Como propus meu cronograma acima, vou poder discutir e coletar as informações necessárias durante o período de integração com a comunidade.

Vou pesquisar as várias seções de acordo com o CHAOSS e manter as conversas na lista de e-mails. Vou tentar fazer perguntas de esclarecimento aos meus mentores e à comunidade, dependendo dos requisitos.

Para ter discussões concisas, também vou participar de chamadas semanais.

3.) Como você pretende manter a comunidade informada sobre seu progresso e quaisquer problemas ou dúvidas que possa ter ao longo do projeto?

Para ter flexibilidade e transparência, vou tentar conversar sobre a discussão da lista de e-mails para tirar minhas dúvidas.

Vou compartilhar meu progresso semanal em uma postagem no blog, que vai incluir a documentação do scrum e os desafios enfrentados, que serão compartilhados na lista de e-mails da comunidade para alcançar um público maior dentro da organização de código aberto.

Também participaria de reuniões semanais da comunidade para discutir as principais questões e fazer sugestões.

Também pretendo criar um quadro do Trello com as tarefas semanais disponíveis. Os mentores podem usar esse quadro para entender de forma clara e concisa os problemas e recursos atuais em que estão trabalhando.

4.) O que você vai fazer se ficar preso no projeto e seu mentor não estiver por perto?

Acredito que o papel do mentor é orientar os alunos na direção certa, e não explicar todos os detalhes do processo. A pesquisa e a implementação do projeto são de responsabilidade exclusiva do estudante. Tendo isso em mente, só vou tentar receber ajuda do meu mentor como último recurso.

No entanto, se o mentor não estiver por perto/ocupado no momento em que eu precisar de ajuda, vou compartilhar o problema que estou tendo na comunidade do CHAOSS. Tenho certeza de que alguém poderá me ajudar com qualquer desafio que eu encontrar. Também vou compartilhar o problema em fóruns on-line/comunidades de desenvolvimento, como dev.to

Além disso, eu tentaria participar de ligações semanais solicitando ajuda na comunidade CHAOSS para tirar minhas dúvidas.