Fase atual:
a temporada de 2021 do programa Documentos foi encerrada em 14 de dezembro de 2021. Consulte o
cronograma.
Sobre a temporada de documentos
A Temporada de Documentos é um programa de sustentabilidade gerenciado pelo Escritório de Programas de Código Aberto do Google. Os objetivos da temporada de documentos são:
- Fornecer suporte a projetos de código aberto para resolver problemas do projeto com documentação
- Dar aos escritores técnicos oportunidades de ganhar 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 em 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 2021
Mudanças no programa de 2021
Em 2019 e 2020, organizações e redatores técnicos se inscreveram no programa Season of Docs separadamente, e os redatores técnicos foram escolhidos para as organizações por administradores do programa. As organizações forneceram mentores para trabalhar com os redatores técnicos, que receberam uma remuneração pelo trabalho baseado em sua localização. O programa mediu se os redatores técnicos, mentores e administradores da organização estavam satisfeitos com a participação no programa, mas não mediu os resultados da documentação.
Em 2021, a equipe da Season of Docs fez mudanças significativas no programa, mudando o foco para a medição de resultados de documentação e permitindo mais flexibilidade para organizações e redatores técnicos.
- As organizações se inscreveram com propostas de projetos, incluindo um orçamento e as métricas propostas
- Os redatores técnicos não se inscreveram mais pelo Google para encontrar organizações, mas sim diretamente para as organizações aceitas
- As organizações aceitas receberam benefícios pelo Open Collective, usados para pagar os redatores técnicos
- A remuneração para os redatores técnicos foi definida pelas organizações
- As organizações enviaram avaliações finais e estudos de caso e responderam a pesquisas de acompanhamento
Descobertas gerais de 2021
Organizações
- Com as mudanças no programa em 2021, houve uma queda de 30% das inscrições nas organizações em 2021 em comparação com 2020. Mas os administradores de 2021 ficaram um pouco mais satisfeitos com o programa do que em 2020 (93% x 91%)
Problemas, documentos e métricas
- A maioria dos projetos se concentrou na criação de documentação para reduzir a carga dos mantenedores (reduzindo problemas/perguntas) e/ou aumentar a participação no projeto (por usuários ou colaboradores).
- 50% das organizações aceitas criaram tutoriais ou tutoriais.
- Mais de 50% das organizações aceitas consideraram a documentação atual incompleta, desorganizada ou desatualizada.
- Os projetos geralmente queriam medir a eficácia da documentação por meio de interações, especialmente menos problemas levantados e mais visitantes aos documentos e participação nos projetos.
- Em novembro de 2022, 25 dos 30 projetos respondendo:
- 18 projetos disseram que tinham atingido suas métricas originais
- 5 projetos atenderam às métricas revisadas
- 2 projetos disseram que ainda era muito cedo para dizer
Participação no programa
- Recrutar, contratar e pagar redatores técnicos foi a parte mais difícil do programa para administradores de organizações.
- Em novembro de 2022, 24 das 30 organizações responderam:
- 18 organizações ainda estavam trabalhando com os redatores técnicos da temporada de Documentos, seja como colaborador contínuo ou recurso para responder a perguntas
- Quatro organizações estavam trabalhando com os redatores técnicos da temporada de Documentos em uma função remunerada
- 18 organizações ainda estavam trabalhando com os redatores técnicos da temporada de Documentos, seja como colaborador contínuo ou recurso para responder a perguntas
Destaques de 2021
- Vários projetos indicaram que o redator técnico pretendia continuar trabalhando com o projeto após o final do programa Season of Docs
- A Metanorma fez com que tantos redatores técnicos qualificados se inscrevessem que encontraram fundos para contratar mais um escritor para trabalhar ao lado da temporada de documentos apoiados durante o programa
- A Moja Global descobriu que a comunidade estava muito engajada na documentação e criou um novo grupo de trabalho para permitir a participação de mais colaboradores na documentação do projeto.
Dados resumidos de 2021
Em 2021, 82 organizações se inscreveram e 30 organizações de código aberto foram aceitas no programa. Consulte o guia Como criar sua inscrição para ver os critérios de seleção. A lista completa das organizações participantes pode ser encontrada no site da temporada de documentos do Google. Todas as 30 organizações aceitas enviaram o relatório final do estudo de caso para concluir a participação no programa de 2021.
Sobre as organizações
As organizações que participaram da Temporada de Documentos 2021 representaram uma gama diversificada de projetos de código aberto. A coorte de 2021 incluiu:
- Grandes projetos de linguagem, como Julia, Perl e R
- Projetos nas áreas de educação, clima, fintechs, saúde, serviços de biblioteca, aprendizado de máquina, espectrometria em massa, contratos públicos e robótica
- Projetos focados no desenvolvedor, incluindo ferramentas de engenharia de caos, fuzzers, SDKs de chatbot, pipelines de análise de composição de software, ferramentas de monitoramento de desempenho e ferramentas de programação visual
- Projetos de documentação para ferramentas de documentação, como Redocly e Metanorma
Os projetos do ecossistema Python foram a maior subcategoria. A coorte de 2021 incluiu ArviZ, NumPy, MicroPython, PyMC3, PyTorch-Ignite e SymPy.
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 que indicassem qual licença de código aberto eles usaram.
Os problemas de documentação descritos pelas organizações de 2021 são muito comuns em projetos de código aberto e na documentação técnica em geral.
Os principais problemas que as organizações esperavam resolver no programa de 2021 incluíam:
As organizações podem relatar vários problemas de documentação. Para saber mais detalhes, consulte a página de resultados da temporada de Documentos Google 2021, que inclui links para estudos de caso completos de cada organização.
Tipos de documentação criados
Os tutoriais foram o tipo de documentação mais mencionado nos estudos de caso de 2021.
Outros tipos de documentação mencionados nos estudos de caso incluem pipeline de documentos como código, diagrama, glossário, guia de estilo, perguntas frequentes, internacionalização, codelab, modelo de conteúdo, módulos, documentação de conceito, mensagens de erro, pesquisa de usuário, arquivo README, base de conhecimento.
Algumas categorias são imprecisas, e um único projeto de documentação pode conter vários tipos ou recursos de documentação.
Vários projetos foram referenciados especificamente usando o framework da diátáxico como guia para o planejamento dos tipos de documentação.
Para saber mais detalhes, consulte a página de resultados da temporada de Documentos Google 2021, que inclui links para estudos de caso completos de cada organização.
Orçamentos
Em 2021, a solicitação de orçamento médio foi de US $10.200, e a mediana foi de US $10.000. Apenas três organizações solicitaram e receberam a concessão máxima possível (US$ 15 mil) e outras três solicitaram a menor concessão possível (US$ 5 mil).
As métricas
os projetos descreveram em seus estudos de caso as métricas que estavam usando para avaliar o sucesso de seus projetos de documentação.
As principais métricas propostas foram:
Outras métricas propostas incluem estrelas do GitHub, tempo gasto na página, conversões da lista de e-mails, testes qualitativos de usuário, número de participantes em fóruns, número de parceiros/voluntários/integrações.
Devido ao curto período entre a conclusão dos projetos de redação técnica e o envio dos estudos de caso, a maior parte da coorte de 2021 não conseguiu coletar dados suficientes para determinar se as métricas iniciais foram cumpridas ou não.
Para saber mais detalhes, consulte a página de resultados da temporada de Documentos Google 2021, que inclui links para estudos de caso completos de cada organização.
Como trabalhar com redatores técnicos
A maior mudança no programa Season of Docs de 2021 envolveu a forma como os projetos funcionavam com redatores técnicos. Em temporadas anteriores, os redatores técnicos se candidataram diretamente ao Google e receberam os projetos dos administradores do programa e receberam um salário fixo diretamente do Google.
Em 2021, os redatores técnicos se inscreveram diretamente nos projetos, e os projetos definiram o orçamento para remuneração de escritores técnicos, com pagamentos feitos pelo Fundo Open Collective da temporada dos Documentos Google.
A maioria dos projetos participantes do programa de 2021 tinha pouca ou nenhuma experiência em recrutar ou contratar redatores técnicos, e muitos projetos apontaram essa parte do processo como uma que precisa de mais suporte. Em resposta a esse feedback, a equipe da Temporada de Documentos adicionou documentação para a criação de contratos de escritor técnico ao guia da programação.
Recomendações de contratação
Os projetos foram solicitados a fazer recomendações para outros projetos interessados em participar da temporada de documentos. As principais recomendações de contratação foram:
- Compartilhe os materiais de recrutamento para escritores técnicos o mais cedo possível, mesmo antes de ser aceito no programa. Peça para sua comunidade indicar possíveis candidatos.
- Compartilhe amplamente fora dos canais do projeto. Use uma linguagem inclusiva e incentive candidatos de contextos sub-representados a se inscreverem.
- Entenda quais ferramentas são essenciais para o seu processo de criação de documentação e recrute redatores técnicos com experiência no uso dessas ferramentas.
- Crie expectativas claras para o redator técnico sobre entregas e marcos, canais de comunicação e check-ins, processos e prazos de pagamento.
- Considere investir em membros da comunidade e ajudá-los a crescer como redatores técnicos usando o redator técnico da temporada de Documentos para fornecer orientação e coaching.
- Reserve mais tempo do que o esperado para integrar redatores técnicos, responder a perguntas e fornecer suporte durante o programa, especialmente se o redator técnico não tiver experiência prévia no domínio do projeto.
- Documente seu processo de recrutamento, contratação e integração para usar em projetos futuros.
Observação: nem todos os projetos indicados nos estudos de caso em que recrutaram os candidatos a redator técnico.
Problemas comuns ao trabalhar com redatores técnicos
Os redatores técnicos de vários projetos tiveram que desistir por causa da COVID ou de outras doenças, ou por conta das responsabilidades familiares relacionadas à pandemia. Alguns projetos relataram problemas de comunicação envolvendo incompatibilidades de fuso horário ou problemas de conectividade com a internet.
Os projetos descobriram que subestimaram as dificuldades envolvidas na integração em suas comunidades ou na configuração do conjunto de ferramentas de documentos do projeto.
Alguns projetos tiveram atrasos no pagamento dos redatores técnicos por causa de problemas bancários com o Open Collective ou porque os países de origem deles tinham restrições de pagamento.
A documentação do programa sobre as taxas da Open Collective não estava clara: o Google cobria as taxas de transação do Open Collective para a transferência inicial de fundos para os projetos, mas não as taxas de transação impostas por alguns outros canais de pagamento (como taxas de conversão de moeda). Trabalharemos para tornar isso mais claro na documentação de programas futuros.
Pesquisas de acompanhamento
Como parte do programa Season of Docs, os projetos foram convidados a participar de pesquisas de acompanhamento. Três pesquisas foram enviadas em maio, agosto e novembro de 2022.
A pesquisa de acompanhamento solicitou que os projetos confirmassem que a proposta e os links do estudo de caso ainda estavam ativos. A pesquisa também incluiu perguntas sobre o sucesso de seus projetos (conforme determinado pelas métricas que eles definiram em seu estudo de caso) e a participação contínua e a remuneração dos redatores técnicos do projeto:
- Você ainda está trabalhando com o redator técnico da temporada de Documentos?
- Se o redator técnico ainda estiver trabalhando com seu projeto, ele está sendo remunerado de alguma forma?
- Neste ponto, você acha que seu projeto de documentação foi bem-sucedido?
Perguntas futuras
Como sempre, quanto mais aprendemos sobre a documentação em código aberto, mais queremos aprender! Nas próximas temporadas, esperamos aprender:
- Se os domínios do projeto estão correlacionados com a escolha do tipo de documento ou da escolha de métricas
- Quais práticas de contratação e integração de escritores técnicos são mais eficazes para a conclusão do projeto e a retenção de escritores técnicos
- Cronogramas razoáveis para medir a eficácia da documentação
Embora haja muitas questões que gostaríamos de investigar, também queremos respeitar o tempo dos administradores e mantenedores de projetos de código aberto que participam da temporada de documentos. A principal prioridade do programa é apoiar projetos na solução de problemas com a documentação.