Fase atual:
a temporada de documentos de 2021 terminou em 14 de dezembro de 2021. Consulte a
linha do tempo.
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:
- Dar 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 com 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 2021
Mudanças no programa de 2021
Em 2019 e 2020, as organizações e os redatores técnicos se inscreveram no programa Season of Docs separadamente, e os redatores técnicos foram combinados com as organizações por administradores do Season of Docs. As organizações forneceram mentores para trabalhar com os redatores técnicos, que receberam um salário pelo trabalho baseado na localização. O programa mediu se os redatores técnicos, os mentores e os 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 medir os resultados da documentação e permitir mais flexibilidade para as organizações e os redatores técnicos.
- Organizações aplicadas com propostas de projeto, incluindo um orçamento e métricas propostas
- Os redatores técnicos não se inscreveram mais por meio do Google para corresponder a organizações, mas foram aplicados diretamente às organizações aceitas
- As organizações aceitas receberam subsídios pelo Open Collective, que costumavam pagar os redatores técnicos
- A remuneração dos 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, menos organizações se inscreveram (30% menos delas em 2021 em comparação com 2020), mas os administradores de 2021 ficaram um pouco mais satisfeitos com o programa (93% x 91%).
Problemas, documentos e métricas
- A maioria dos projetos se concentrou na criação de documentação para reduzir a carga do mantenedor (reduzindo problemas/perguntas) e/ou aumentar a participação no projeto (por usuários ou colaboradores do projeto).
- 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 questões levantadas e mais visitantes aos documentos e participação nos projetos.
- Em novembro de 2022, com 25 de 30 projetos respondendo:
- 18 projetos disseram que tinham atingido suas métricas originais
- 5 projetos alcançaram as métricas revisadas
- 2 projetos disseram que ainda é 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 da organização.
- 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 colaboradora contínua 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 colaboradora contínua 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 Temporada de Documentos
- A Metanorma fez com que tantos redatores técnicos qualificados se inscrevessem que encontraram fundos correspondentes para contratar mais um redator para trabalhar ao lado de um escritor com suporte na temporada de Documentos Google durante o programa.
- A Moja Global descobriu que a comunidade estava muito engajada na documentação e criou um novo Grupo de trabalho de documentação para que mais colaboradores pudessem participar da documentação do projeto.
Dados de resumo de 2021
Em 2021, 82 organizações se inscreveram e 30 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. 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 ampla variedade de projetos de código aberto. A coorte de 2021 incluiu:
- Projetos de linguagem grandes, como Julia, Perl e R
- Projetos de educação, clima, fintechs, saúde, serviços de biblioteca, aprendizado de máquina, espectrometria de massa, contratos públicos e robótica
- Projetos voltados para desenvolvedores, incluindo ferramentas de engenharia de caos, fuzzers, SDKs de bot de bate-papo, 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.
Solicitamos que os projetos 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.
Entre os principais problemas que as organizações esperavam resolver no programa de 2021 estão:
As organizações podem informar vários problemas de documentação. Para saber mais, consulte a página de resultados da temporada de Documentos Google 2021, com 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.
Há outros tipos de documentação mencionados nos estudos de caso: 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, Leiame, base de conhecimento.
Algumas dessas categorias são confusas, e um único projeto de documentação pode conter vários tipos ou recursos de documentação.
Vários projetos foram referenciados especificamente com o framework Diátaxis como guia para o planejamento dos tipos de documentação.
Para saber mais, consulte a página de resultados da temporada de Documentos Google 2021, com links para estudos de caso completos de cada organização.
Orçamentos
Em 2021, a solicitação de orçamento média foi de US $10.200, e a mediana foi de US $10.000. Apenas três organizações solicitaram e receberam a doação máxima possível (US$ 15 mil) e outras três solicitaram a doação mais baixa possível (US$ 5 mil).
As métricas
projetos delineados 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 foram estrelas do GitHub, tempo gasto na página, conversões de 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 ou não atendidas.
Para saber mais, consulte a página de resultados da temporada de Documentos Google 2021, com 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. Nas temporadas anteriores, os redatores técnicos se inscrevevam diretamente no Google, eram designados aos administradores do programa com os projetos, e recebiam um salário fixo diretamente do Google.
Em 2021, os redatores técnicos se inscreveram nos projetos diretamente, e os projetos definiram o orçamento para a compensação de escritores técnicos, com pagamentos feitos pelo Fundo Open Collective da temporada de Documentos.
A maioria dos projetos que participaram do programa de 2021 tinha pouca ou nenhuma experiência em recrutar ou contratar redatores técnicos, e muitos projetos chamavam essa parte do processo como uma que precisa de mais apoio. Em resposta a esse feedback, a equipe da temporada de documentos adicionou documentação para a criação de contratos de redação técnica ao guia de 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 redatores técnicos o mais cedo possível, mesmo antes de você ser aceito no programa. Peça para sua comunidade indicar possíveis candidatos.
- Compartilhe amplamente fora dos canais do projeto. Usar uma linguagem inclusiva e incentivar diretamente 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.
- Criar expectativas claras para o redator técnico sobre entregas e marcos, canais de comunicação e verificações, e processos e prazo 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 mentoria e treinamento.
- Reservar mais tempo do que você espera para contratar redatores técnicos, responder perguntas e fornecer suporte durante o programa, especialmente se o redator técnico não tiver experiência anterior na área 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 seus candidatos a redatores técnicos.)
Problemas comuns ao trabalhar com redatores técnicos
Redatores técnicos de vários projetos tiveram que desistir por causa da COVID ou de outras doenças, ou por causa de 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 às 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 o país de origem deles tinha restrições de pagamento.
A documentação do programa sobre as taxas do Open Collective não estava clara: o Google cobria as taxas de transação do Open Collective referentes à 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 esclarecer isso na documentação de programas futuros.
Pesquisas de acompanhamento
Como parte do programa Season of Docs, os projetos foram solicitados 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 confirmem 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?
- Você acha que seu projeto de documentação foi bem-sucedido?
Perguntas futuras
Como sempre, quanto mais aprendemos sobre 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étrica
- Quais práticas de contratação e integração de redatores técnicos são mais eficazes para a conclusão do projeto e para a retenção de redatores técnicos
- Cronogramas razoáveis para medir a eficácia da documentação
Embora haja muitas perguntas 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 documentação.