Fase atual:
O programa "Temporada de documentos" de 2021 terminou em 14 de dezembro de 2021. Consulte
linha do tempo.
Sobre a Season of Docs
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 2021
Mudanças no programa de 2021
Em 2019 e 2020, as organizações e os redatores técnicos se inscreveram separadamente no programa Season of Docs, e os redatores técnicos foram combinados com as organizações pelos administradores do programa. As organizações forneceram mentores para trabalhar com os redatores técnicos, que receberam uma bolsa para o trabalho com base na 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 Temporada de documentos fez mudanças significativas no programa, mudando o foco para a medição dos resultados da documentação e permitindo mais flexibilidade para as organizações e redatores técnicos.
- Organizações que se candidataram com propostas de projeto, incluindo um orçamento e métricas propostas
- Os redatores técnicos não precisam mais se inscrever no Google para serem associados a organizações, mas podem se inscrever diretamente nas organizações aceitas
- As organizações aceitas receberam bolsas pelo Open Collective, que foram usadas para pagar os redatores técnicos.
- A compensaçã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
Resultados gerais de 2021
Organizações
- As mudanças no programa de 2021 levaram a menos organizações se inscreverem (30% a menos em 2021 do que em 2020), mas os administradores de 2021 estavam um pouco mais satisfeitos com o programa do que os de 2020 (93% contra 91%)
Problemas, tipos de documentos e métricas
- A maioria dos projetos se concentrou na criação de documentação para reduzir a carga de trabalho 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 conteúdo de tutoriais ou instruções.
- Mais de 50% das organizações aceitas consideraram que a documentação atual delas era insuficiente, 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 nos documentos e participação nos projetos.
- Em novembro de 2022, 25 dos 30 projetos responderam:
- 18 projetos disseram que atingiram as métricas originais
- Cinco projetos atenderam às métricas revisadas
- Dois 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 os 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 (como colaboradores contínuos ou como recurso para responder a perguntas)
- 4 organizações estavam trabalhando com redatores técnicos da Temporada de documentos em um cargo remunerado
- 18 organizações ainda estavam trabalhando com os redatores técnicos da Temporada de documentos (como colaboradores contínuos ou como 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 fim do programa "Temporada de documentos".
- A Metanorma recebeu tantas inscrições de redatores técnicos qualificados que conseguiu encontrar fundos para contratar outro redator para trabalhar com o escritor apoiado pela Temporada de Docs durante o programa.
- A Moja Global descobriu que a comunidade estava muito envolvida com a documentação e criou um novo grupo de trabalho para permitir que mais colaboradores participem da documentação do projeto.
Dados de resumo de 2021
Em 2021, 82 organizações se inscreveram e 30 organizações de código aberto foram aceitas no programa. Consulte os critérios de seleção no guia "Como criar seu aplicativo". A lista completa de organizações participantes está disponível no site da Season of Docs. 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 de 2021 representaram uma variedade de projetos de código aberto. A turma de 2021 incluiu:
- Projetos de linguagem grandes, como Julia, Perl e R
- Projetos em educação, clima, fintech, 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 do 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 turma 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 para indicar 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 informar vários problemas de documentação. Para mais detalhes, consulte a página de resultados da Temporada de documentos de 2021, que inclui links para estudos de caso completos de cada organização.
Tipos de documentação criada
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 incluíam 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, readme, base de conhecimento.
Algumas dessas categorias são vagas, e um único projeto de documentação pode conter vários tipos ou recursos de documentação.
Vários projetos referenciaram especificamente o framework Diátaxis como um guia para planejar os tipos de documentação.
Para mais detalhes, consulte a página de resultados da Temporada de documentos de 2021, que inclui links para estudos de caso completos de cada organização.
Orçamentos
Em 2021, o orçamento médio solicitado foi de US $10.200, e a mediana foi de US $10.000. Apenas três organizações solicitaram e receberam a bolsa máxima possível (US$ 15 mil), e outras três solicitaram a menor bolsa possível (US$ 5 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:
Outras métricas propostas incluíam estrelas do GitHub, tempo gasto na página, conversões de lista de e-mails, testes de usuários qualitativos, número de participantes em fóruns, número de parceiros/voluntários/integrações.
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 do grupo de 2021 não conseguiu coletar dados suficientes para determinar se as métricas iniciais foram atendidas ou não.
Para mais detalhes, consulte a página de resultados da Temporada de documentos de 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 "Temporada de documentos" em 2021 envolveu a forma como os projetos trabalharam com redatores técnicos. Nas temporadas anteriores, os redatores técnicos se candidatavam diretamente ao Google, eram combinados com os projetos pelos administradores do programa e recebiam um pagamento fixo diretamente do Google.
Em 2021, os redatores técnicos se candidataram diretamente aos projetos, que definiram o orçamento para a remuneração deles, com pagamentos feitos pelo fundo Open Collective do Season of Docs.
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 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 criar contratos de redatores técnicos ao guia do programa.
Recomendações de contratação
Os projetos foram convidados 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 ser aceito no programa. Peça à sua comunidade para indicar possíveis candidatos.
- Compartilhe amplamente fora dos canais do projeto. Use uma linguagem inclusiva e incentive diretamente candidatos de origens sub-representadas a se inscrever.
- Entenda quais ferramentas são essenciais para o processo de criação de documentação e recrute redatores técnicos com experiência em usar essas ferramentas.
- Crie expectativas claras para o redator técnico sobre entregas e marcos, canais de comunicação e check-ins, além de processos e prazos de pagamento.
- Invista nos membros da comunidade e ajude-os a crescer como escritores técnicos usando a Temporada de documentos para oferecer orientação e treinamento.
- Reserve mais tempo do que o esperado para a integração de redatores técnicos e para responder a perguntas e oferecer suporte durante o programa, especialmente se o redator técnico não tiver experiência anterior no domínio do seu projeto.
- Documente seu processo de recrutamento, contratação e integração para usar em projetos futuros.
Observação: nem todos os projetos indicaram nos estudos de caso como recrutaram os candidatos a redatores técnicos.
Problemas comuns ao trabalhar com redatores técnicos
Redatores técnicos de vários projetos tiveram que sair devido à COVID ou 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 da cadeia de ferramentas de documentos do projeto.
Alguns projetos tiveram atrasos no pagamento dos redatores técnicos devido a problemas bancários com o Open Collective ou porque os países de origem dos redatores tinham 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 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). Vamos trabalhar para deixar isso mais claro na documentação de programas futuros.
Pesquisas de acompanhamento
Como parte do programa "Temporada de documentos", 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 pediu que os projetos confirmassem se os links da proposta e do estudo de caso ainda estavam ativos. A pesquisa também incluiu perguntas sobre o sucesso dos projetos (conforme determinado pelas métricas definidas no estudo de caso) e a participação e compensação contínua 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?
Futuras perguntas
Como sempre, quanto mais aprendemos sobre a documentação de 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 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 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 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.