Season of Docs é um programa de sustentabilidade gerenciado pelo Open Source Programs Office do Google. Os objetivos da Temporada de Documentação são:
- Oferecer suporte a projetos de código aberto para resolver problemas de documentação
- Oferecer 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 na documentação de código aberto
Mais informações sobre o Season of Docs estão disponíveis no site do programa.
Visão geral do programa de 2022
Como a Temporada de Documentação funciona
No Season of Docs, 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 ajudar a resolver o problema
- Como o projeto vai medir a eficácia da documentação (métricas)
- Um cronograma para o trabalho
- Um orçamento do projeto
- Qualquer informação adicional, como a experiência da organização em programas semelhantes ou qualquer outra coisa que ajude os administradores do Season of Docs a entender o projeto e o problema
Depois de serem aceitas no programa, as organizações recrutam e contratam os próprios escritores técnicos diretamente. O Season of Docs usa o Open Collective para financiar as organizações, e as organizações pagam os escritores técnicos pelo Open Collective. Os orçamentos e pagamentos de projetos são transparentes. Os orçamentos estão incluídos nas propostas de projetos da organização disponíveis no site do Season of Docs, e os pagamentos ficam visíveis na conta do Open Collective do Season of Docs.
As organizações são consideradas como tendo concluído o programa quando enviam o relatório de estudo de caso. As organizações também precisam concluir 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 agradável desse projeto foi ver [nossos escritores técnicos] crescerem em funções de liderança na nossa comunidade. Os dois colaboradores agora lideram reuniões de grupos de trabalho e da comunidade, além de contribuir para o design e a manutenção dos nossos projetos." —moja-global
"[A Temporada de Documentação] nos ajudou a recrutar dois escritores técnicos talentosos, o que é muito difícil em uma configuração normal. Eles continuam sendo colaboradores ativos de código aberto no 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, o benefício da CZI também oferece bolsas 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 do novo manual." —OpenMS
Dados resumidos de 2022
Em 2022, o programa Season of Docs aceitou 31 projetos de 67 inscrições, e 30 projetos concluíram o programa. Das 31 organizações aceitas, 17 eram candidatos recorrentes.
Os 31 projetos aceitos contrataram 58 escritores técnicos. Mais de 190 escritores técnicos indicaram interesse em participar do programa adicionando informações de contato e links para os portfólios deles no repositório do GitHub da Season of Docs.
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 acharam que o projeto de documentação foi bem-sucedido
Sobre as organizações
As organizações que participaram da Temporada de Documentação 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 para usuários finais, 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 de 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 usavam.
Sobre os projetos de documentação
Problemas de 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 Documentação de 2022, que tem links para as propostas de projetos originais e estudos de caso completos de cada organização.
Tipos de documentação criados
A documentação de instruções foi o tipo de documentação mais mencionado nos estudos de caso de 2022.
Outros tipos de documentação mencionados nos estudos de caso incluíam:
- Guia de início rápido
- Glossário
- Perguntas frequentes
- Base de conhecimento
- Componentes
- Conteúdo de blog/rede 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 Documentação de 2022, que tem links para as propostas de projetos originais e estudos de caso completos de cada organização.
Orçamentos
A solicitação de orçamento média foi de US $11.679, e a mediana foi de US $12.150. Cinco organizações solicitaram e receberam o maior benefício disponível (US$ 15 mil), e três solicitaram o menor (entre US $5 mil e US$ 7 mil).
As métricas
Os projetos descreveram nos estudos de caso as métricas que estavam usando para avaliar o sucesso dos projetos de documentação.
As principais métricas propostas foram:
Outras métricas propostas incluíam:
- Mais solicitações de envio/contribuições de documentação
- Mais feedback direto nas páginas de documentação
- Tempo gasto na página
- Problemas levantados (como um proxy para uso)
- Participantes em fóruns
- Número de parceiros/voluntários/integrações
- Taxa de rejeição reduzida
- Maior conscientização na comunidade
Devido à pequena janela entre a conclusão dos projetos de redação técnica e o envio dos estudos de caso, a maioria da turma 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.
À medida que recebermos respostas às pesquisas de acompanhamento em 2023, vamos atualizar este relatório para adicionar informações sobre quais projetos atingiram ou revisaram as métricas.
Para mais detalhes, consulte a página de resultados da Temporada de Documentação de 2022, que tem links para as propostas de projetos originais e estudos de caso completos de cada organização.
Como trabalhar com escritores técnicos
No programa Season of Docs, os projetos precisam recrutar, entrevistar, contratar e pagar escritores técnicos diretamente. Os escritores 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 escritores técnicos.
Práticas recomendadas para contratar escritores técnicos para projetos de código aberto
Os projetos foram solicitados a compartilhar as práticas recomendadas para recrutar, contratar e trabalhar com escritores técnicos. As principais recomendações foram:
Recrutamento
- Entreviste menos candidatos e use uma sessão de 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 na linguagem ou nas ferramentas do projeto
- Faça perguntas diretas sobre como o escritor técnico vai adquirir o conhecimento de domínio necessário para trabalhar com o projeto
- Alguém com entusiasmo pela missão do projeto e que compartilha os valores principais de código aberto tem mais chances de permanecer motivado durante todo o projeto
- Esteja aberto a candidatos de todo o mundo, porque uma diversidade de pontos de vista e origens vai ajudar seu projeto. No entanto, tenha em mente que ter escritores e mentores em muitos fusos horários conflitantes pode exigir muito esforço extra para manter uma boa comunicação
Contratação
- Use um contrato que especifique claramente as entregas, os cronogramas de pagamento e os compromissos de tempo específicos
- Se o projeto tiver muitas incógnitas, inclua um marco para descoberta ou pesquisa separado da criação de documentação
Coordenação e comunicação
- Mantenha um registro de reuniões gravando decisões para facilitar a compreensão do contexto e das próximas etapas para todos que trabalham no projeto
- Seja claro sobre o que é esperado da comunicação e com que frequência, sejam chamadas semanais, e-mails diários ou atualizações de status em um canal de chat
- Seja responsivo e dê feedback claro que inclua o "porquê" e não apenas o "o quê"
- Conecte seus escritores técnicos à comunidade mais ampla para dar contexto e socializar o trabalho deles
Processos e ferramentas
- Crie um processo de documentação que dure além do programa Season of Docs e que toda a comunidade possa contribuir
- A revisão da documentação vai levar pelo menos o mesmo tempo e é tão intensa quanto a revisão de código. Portanto, reserve tempo suficiente para ela
Algumas recomendações foram editadas e condensadas para fins de esclarecimento.
Assim como no programa de 2021, a maioria dos escritores técnicos do Season of Docs de 2022 se inscreveu diretamente nas organizações com que trabalharam.
Problemas comuns ao trabalhar com escritores técnicos
Menos projetos relataram problemas ao trabalhar com os escritores técnicos no programa de 2022. O maior problema foi a incapacidade dos escritores técnicos de concluir o programa devido a doença, aceitação de um emprego em tempo integral ou incapacidade de cumprir o compromisso de tempo.
Um projeto informou que o projeto de documentação dependia do trabalho realizado 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 escritor técnico precisava documentar foi confiscado pelo Ministério da Defesa no país do escritor 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.
Perguntas futuras
Como sempre, quanto mais aprendemos sobre documentação em código aberto, mais queremos aprender!
Nas próximas temporadas, esperamos:
- Coletar mais metadados de projetos para procurar correlações entre a idade do projeto, o tamanho da comunidade ou as necessidades de linguagem e documentação
- Analisar projetos de documentação para ver se eles podem ser generalizados em modelos compartilháveis
- Desenvolver uma rubrica para entrevistar escritores 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 mantenedores de projetos de código aberto que participam do Season of Docs. A principal prioridade do programa é ajudar os projetos a resolver problemas de documentação.