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:
- Ferramentas de desenvolvimento, como AsyncAPI e SpyderIDE
- Linguagens e frameworks de programação, como Julia, LFortran, R e p5.js
- Projetos científicos, como CERN-HSF e SymPy
- Aplicativos do usuário final, como Mautic, Open Food Facts, Talawa e Ushahidi
- Projetos de hardware e robótica, como ExpressLRS e Open-RMF
- Projetos de dados, como GeomScale, GeomStats, OpenMined e Weaviate
- Projetos de nuvem e infraestrutura, como cert-manager, NimbleEdge e Cilium
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.
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:
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.
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:
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.
Problemas comuns ao trabalhar com redatores técnicos
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.