Relatório de estudo de caso de 2022

Fase atual:
Estudos de caso publicados. Consulte linha do tempo.

O Season of Docs é um programa de sustentabilidade gerenciado pelo Google Open Source Programs Office. Os objetivos da Season of Docs são:

  • Oferecer suporte a projetos de código aberto para resolver problemas de documentação
  • Oferecer aos redatores técnicos oportunidades de adquirir experiência em código aberto
  • Aumentar a conscientização sobre código aberto, documentação e redação técnica
  • Coletar e compartilhar informações sobre métricas eficazes na documentação de código aberto

Mais informações sobre a Temporada de documentos estão disponíveis no site do programa.

Visão geral do programa de 2022

Como funciona a Season of Docs

Na Temporada de documentos, as organizações se inscrevem enviando uma proposta de projeto. A proposta de projeto inclui:

  • Informações sobre a organização
  • Uma descrição do problema que o projeto está enfrentando
  • Como o projeto vai usar a documentação para resolver o problema
  • Como o projeto vai medir a eficácia da documentação (métricas)
  • Uma linha do tempo do trabalho
  • Um orçamento de projeto
  • Outras informações, como a experiência da organização em programas semelhantes ou qualquer outra informação que ajude os administradores da Temporada de documentos a entender o projeto e o problema

Depois de aceitas no programa, as organizações recrutam e contratam diretamente os próprios redatores técnicos. O Season of Docs usa o Open Collective para financiar as organizações, e as organizações pagam os redatores técnicos pelo Open Collective. Os orçamentos e pagamentos do projeto são transparentes. Os orçamentos estão incluídos nas propostas de projetos da organização disponíveis no site do programa, e os pagamentos aparecem na conta do coletivo aberto do programa.

As organizações são consideradas como tendo concluído o programa quando enviam o relatório do estudo de caso. As organizações também precisam preencher avaliações mensais durante o programa e três pesquisas de acompanhamento trimestrais durante o ano seguinte à conclusão do programa.

Destaques de 2022

"Depois que o novo documento foi lançado, as visitas diárias ao Casbin e ao Casdoor quase dobraram, e as taxas de rejeição caíram cerca de 30%." —Casbin

"Um resultado incrível desse projeto foi ver [nossos redatores técnicos] crescerem e assumirem cargos de liderança na nossa comunidade. Agora, os dois colaboradores lideram reuniões de grupos de trabalho e da comunidade, além de contribuir com o design e a manutenção dos nossos projetos." —moja-global

"[O GSoD] nos ajudou a recrutar dois redatores técnicos talentosos, o que é muito difícil em uma configuração regular. Eles continuam sendo colaboradores ativos do OpenMined e tivemos uma ótima experiência de trabalho com eles." —OpenMined

"Além disso, o novo manual é muito mais fácil para iniciantes em espectrometria de massa computacional. Para ilustrar esse ponto: a bolsa CZI também oferece estipêndios para pessoas historicamente desfavorecidas, e alguns premiados usaram o novo manual do OpenMS para iniciar o período de estágio de seis semanas e deram avaliações positivas sobre o novo manual." —OpenMS

Dados de resumo de 2022

Em 2022, a Temporada de documentos aceitou 31 projetos de 67 inscrições, e 30 projetos concluíram o programa. Das 31 organizações aceitas, 17 já haviam se candidatado.

Os 31 projetos aceitos contrataram 58 redatores técnicos. Mais de 190 redatores técnicos indicaram interesse em participar do programa adicionando informações de contato e links para os portfólios no repositório do GitHub da Temporada de documentos.

Para o programa de 2022:

  • 100% das organizações tiveram uma experiência positiva com o processo de inscrição
  • 100% das organizações tiveram uma experiência positiva com a documentação/conteúdo do site do programa
  • 93% das organizações tiveram uma experiência positiva com o programa
  • 90% das organizações sentiram que o projeto de documentação foi bem-sucedido

Sobre as organizações

As organizações que participaram da Temporada de documentos de 2022 representaram uma variedade de projetos de código aberto. A turma de 2022 incluiu:

Um gráfico de barras mostrando os domínios representados pelos projetos aceitos: dados: 5 projetos; ferramentas de desenvolvimento: 4 projetos; aplicativos para usuários finais: 7 projetos; hardware e robótica: 2 projetos; infraestrutura e nuvem: 4 projetos; linguagens e ferramentas de programação: 3 projetos; ciência e medicina: 3 projetos; segurança: 1 projeto; social e comunicações: 1 projeto; ferramentas e frameworks da Web: 1 projeto

Não coletamos metadados sobre os projetos, como data de fundação, distribuição geográfica dos colaboradores, número de colaboradores ou tamanho da base de usuários.

Pedimos aos projetos para indicar qual licença de código aberto eles usaram.

Um gráfico de barras que mostra o número de projetos que usam cada licença de OSS: AGPL-3.0: 2 projetos; Apache-2.0: 9 projetos; BSD-3-Cláusula: 4 projetos; GPL-3.0: 3 projetos; LGPL 3.0: 3 projetos; MIT: 5 projetos; Licença pública Mozilla 2.0: 2 projetos; BSL-1.0, GPL-2.0, LGPL-2.1: um projeto cada

Sobre os projetos de documentação

Problemas com a documentação

Os principais problemas que as organizações esperavam resolver com a documentação no programa de 2022 incluíam:

Um gráfico de barras mostrando os problemas relatados pelas organizações: falta documentação para casos de uso específicos de aspectos de um projeto: 16 projetos; a documentação está desorganizada: 11 projetos; a documentação está desatualizada: 7 projetos; a documentação não é consistente: 1 projeto; a documentação precisa ser convertida em uma ferramenta, plataforma ou formato diferente: 8 projetos

As organizações podem informar vários problemas de documentação. Para mais detalhes, consulte a página de resultados da Temporada de documentos 2022, que inclui links para as propostas de projeto originais e estudos de caso completos de cada organização.

Tipos de documentação criada

A documentação de instruções foi o tipo de documento mais mencionado nos estudos de caso de 2022.

Um gráfico mostrando os tipos de documentação criados:  tutoriais: 12 projetos; tutoriais: 9 projetos; referência: 8 projetos; página de destino: 5 projetos; documentos da API: 4 projetos; diagramas, capturas de tela, ilustrações: 4 projetos; introdução, guia de estilo, manual: 3 projetos cada; exemplos, documentação de conceito, pesquisa de usuário: 2 projetos cada

Outros tipos de documentação mencionados nos estudos de caso incluem:

  • Guia de início rápido
  • Glossário
  • Perguntas frequentes
  • Base de conhecimento
  • Componentes
  • Conteúdo de blog/mídia social
  • Guia do mantenedor

Algumas dessas categorias são vagas, e um único projeto de documentação pode conter vários tipos ou recursos de documentação.

Para mais detalhes, consulte a página de resultados da Temporada de documentos 2022, que inclui links para as propostas de projeto originais e estudos de caso completos de cada organização.

Orçamentos

O orçamento médio solicitado foi de US $11.679, e a mediana foi de US $12.150. Cinco organizações solicitaram e receberam a maior bolsa disponível (US$ 15 mil), e três solicitaram a menor (entre US $5 mil e US$ 7 mil).

As métricas

Os projetos descritos nos estudos de caso mostram as métricas que eles usavam para avaliar o sucesso dos projetos de documentação.

As principais métricas propostas foram:

Um gráfico de barras mostrando as métricas de sucesso da documentação: mais colaboradores/pull requests: 12 projetos; porcentagem total de informações de destino cobertas pelos documentos: 8 projetos; menos problemas/perguntas do projeto: 7 projetos; mais visitantes para uso de documentação/documentos: 6 projetos; Melhor SEO: 5 projetos; aumento da satisfação com a documentação (por pesquisa), aumento do uso do projeto, mais estrelas/forks do GitHub: 3 projetos cada; número total de documentos criados e testes qualitativos do usuário: dois projetos cada

Outras métricas propostas incluídas:

  • Mais solicitações/contribuições de extração de documentação
  • Feedback mais direto nas páginas de documentação
  • Tempo na página
  • Problemas levantados (como um proxy para uso)
  • Participantes em fóruns
  • Número de parceiros/voluntários/integrações
  • Redução da taxa de rejeição
  • Aumento da conscientização na comunidade.

Devido ao curto período entre o término dos projetos de redação técnica e o envio dos estudos de caso, a maioria dos participantes do grupo de 2022 não conseguiu coletar dados suficientes no momento do envio dos estudos de caso para determinar se as métricas iniciais foram atendidas ou não.

À medida que recebermos respostas às pesquisas de acompanhamento em 2023, vamos atualizar este relatório para incluir informações sobre quais projetos alcançaram ou revisaram as métricas.

Para mais detalhes, consulte a página de resultados da Temporada de documentos 2022, que inclui links para as propostas de projeto originais e estudos de caso completos de cada organização.

Como trabalhar com redatores técnicos

No programa "Season of Docs", os projetos precisam recrutar, entrevistar, contratar e pagar os redatores técnicos diretamente. Os redatores técnicos podem se adicionar ao diretório mantido pelo Season of Docs no nosso repositório do GitHub, mas a equipe do Season of Docs não avalia nem recomenda redatores técnicos.

Práticas recomendadas para contratar redatores técnicos para projetos de código aberto

Pedimos aos projetos que compartilhassem as práticas recomendadas para recrutar, contratar e trabalhar com redatores técnicos. As principais recomendações foram:

Recrutamento

  • Entrevistar menos candidatos e usar uma sessão prática ao vivo, em vez de apenas analisar currículos
  • Valorize as habilidades de comunicação escrita e oral em vez da proficiência no idioma ou nas ferramentas do seu projeto.
  • Faça perguntas diretas sobre como o redator técnico vai adquirir o conhecimento de domínio necessário para trabalhar com seu projeto.
  • Alguém que se empolga com a missão do projeto e compartilha os valores principais do código aberto tem mais chances de se manter motivado durante todo o projeto.
  • Aceite candidatos de todo o mundo, porque a diversidade de pontos de vista e origens ajuda seu projeto. No entanto, ter redatores e mentores em muitos fusos horários diferentes pode exigir muito esforço extra para manter uma boa comunicação.

Vagas

  • Use um contrato que especifique claramente os resultados, os cronogramas de pagamento e os compromissos de tempo específicos
  • Se o projeto tiver muitas informações desconhecidas, inclua um marco para descoberta ou pesquisa separado da criação de documentação.

Coordenação e comunicação

  • Mantenha um registro de decisões da reunião para facilitar a compreensão do contexto e das próximas etapas por todos que trabalham no projeto
  • Deixe claro qual comunicação é esperada e com que frequência, sejam ligações semanais, e-mails diários ou atualizações de status em um canal de chat
  • Seja receptivo e dê feedback claro que inclua o "por que", e não apenas o "o que".
  • Conecte seus redatores técnicos à comunidade para dar contexto e socializar o trabalho deles

Processos e ferramentas

  • Crie um processo de documentação que dure além do programa "Temporada de documentos" e que toda a comunidade possa contribuir.
  • A revisão da documentação leva pelo menos o mesmo tempo e é tão intensa quanto a revisão do código. Reserve tempo suficiente para isso.

Algumas recomendações foram editadas e condensadas para ficarem mais claras.

Assim como no programa de 2021, a maioria dos redatores técnicos da Temporada de documentos de 2022 se inscreveu diretamente nas organizações com que trabalharam.

Um gráfico de barras mostrando a origem dos candidatos a redatores técnicos: 18 candidatos se inscreveram diretamente no programa; 6 candidatos participaram do SoD do GitHub ou foram participantes anteriores do SoD; 5 candidatos são membros da comunidade; 3 candidatos não especificaram a origem; 1 candidato se inscreveu pelo site de vagas.

Problemas comuns ao trabalhar com redatores técnicos

Um gráfico de barras mostrando problemas de redatores técnicos: desistência de TW: 4 projetos; problemas de comunicação, integração de TW, habilidades de TW, falta de conhecimento de domínio, hardware confiscado, conflito com outro trabalho em andamento: 1 projeto cada

Menos projetos relataram problemas ao trabalhar com os redatores técnicos no programa de 2022. O maior problema foi a incapacidade de redatores técnicos de concluir o programa devido a doenças, a contratação em um emprego de tempo integral ou a incapacidade de cumprir o compromisso de tempo.

Um projeto informou que o projeto de documentação dependia do trabalho feito como parte do Google Summer of Code e que essas dependências eram difíceis de gerenciar. Outro projeto teve dificuldades quando o hardware que o redator técnico precisava documentar foi confiscado pelo Ministério da Defesa no país do redator e não pôde ser importado.

Pesquisas de acompanhamento

Três pesquisas de acompanhamento serão enviadas aos participantes de 2022 em maio, agosto e novembro de 2023. Vamos atualizar esta seção com os resultados à medida que forem recebidos.

Futuras perguntas

Como sempre, quanto mais aprendemos sobre a documentação de código aberto, mais queremos aprender.

Nas próximas temporadas, esperamos:

  • Coletar mais metadados do projeto para procurar correlações entre a idade do projeto, o tamanho da comunidade ou as necessidades de idioma e documentação
  • Analisar projetos de documentação para saber se eles podem ser generalizados em modelos compartilháveis
  • Desenvolver uma rubrica para entrevistar redatores técnicos em projetos de código aberto

Embora haja muitas perguntas que gostaríamos de investigar, também queremos respeitar o tempo dos administradores e dos administradores de projetos de código aberto que participam da Temporada de documentos. A principal prioridade do programa é ajudar projetos a resolver problemas com a documentação.