Fase atual:
desenvolvimento da documentação. Consulte o
cronograma.
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 2022
Como funciona a temporada dos Documentos Google
Na temporada de documentos, as organizações se inscrevem enviando uma proposta de projeto. A proposta do projeto inclui:
- Informações sobre a organização
- Uma descrição do problema que o projeto está enfrentando
- Como o projeto usará a documentação para ajudar a resolver o problema
- Como o projeto medirá a eficácia de sua documentação (métricas)
- Uma linha do tempo do trabalho
- Um orçamento de projeto
- Informações adicionais, como a experiência da organização em programas semelhantes ou qualquer outra informação que possa ajudar os administradores da temporada de Documentos Google a entender o projeto e problema
Depois de aceitas no programa, as organizações recrutam e contratam seus próprios redatores técnicos diretamente. A Temporada de Documentos usa o Open Collective para financiar as organizações, e as organizações pagam os redatores técnicos por meio do Open Collective. Os orçamentos e os pagamentos de projetos são transparentes. Os orçamentos estão incluídos nas propostas de projetos da organização disponíveis no site da temporada do Documentos, e os pagamentos podem ser acessados na conta do Open Collective da temporada do Documentos.
As organizações são consideradas como concluídas o programa quando enviam o relatório do estudo de caso. Também são solicitadas 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 à Casbin e à Casdoor quase dobraram, e as taxas de rejeição caíram em cerca de 30%."—Casbin
"Um resultado maravilhoso deste projeto foi ver [nossos redatores técnicos] crescerem em cargos de liderança em nossa comunidade. Agora, ambos 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
"[O GSOD] nos ajudou a recrutar dois escritores técnicos talentosos, o que é muito difícil em um ambiente regular, que continuam contribuindo ativamente com sistemas operacionais para o OpenMined e com os quais tivemos uma ótima experiência de trabalho." —OpenMined
“Além disso, o novo manual é muito mais fácil para iniciantes na espectrometria de massa computacional. Para ilustrar esse ponto: a concessão da CZI também oferece subsídios para indivíduos historicamente carentes, e alguns premiados usaram o novo manual do OpenMS para iniciar seu período de estágio de seis semanas e deram avaliações positivas do novo manual.” —OpenMS
Dados do resumo de 2022
Em 2022, o programa Season of Docs aceitou 31 projetos de 67 inscrições, e 30 projetos concluíram com sucesso o programa. Das 31 organizações aceitas, 17 eram solicitações recorrentes.
Os 31 projetos aceitos contrataram 58 redatores técnicos. Mais de 190 redatores técnicos demonstraram interesse em participar do programa adicionando informações de contato e links para seus portfólios no repositório da Season of Docs do GitHub.
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 Google 2022 representaram uma gama diversificada de projetos de código aberto. A coorte 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 de 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 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.
Sobre os projetos de documentação
Problemas de documentação
Os principais problemas que as organizações queriam resolver com a documentação do programa de 2022 incluíam:
As organizações podem relatar vários problemas de documentação. Para saber mais, consulte a página de resultados da temporada de Documentos Google 2022, que inclui as propostas de projetos originais e estudos de caso completos para 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 incluem:
- Guia de início rápido
- Glossário
- Perguntas frequentes
- Base de conhecimento
- Componentes
- Conteúdo de blog/mídias sociais
- Guia do mantenedor
Algumas categorias são imprecisas, e um único projeto de documentação pode conter vários tipos ou recursos de documentação.
Para saber mais, consulte a página de resultados da temporada de Documentos Google 2022, que inclui as propostas de projetos originais e estudos de caso completos para cada organização.
Orçamentos
A solicitação de orçamento médio foi de US $11.679 e a mediana foi de US $12.150. Cinco organizações solicitaram e receberam a concessão mais alta disponível (US$ 15 mil) e três solicitaram a menor (entre US $5 mil e US$ 7 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:
- Mais solicitações/contribuições de envio de documentação
- Feedback mais direto sobre as 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
- Redução da taxa de rejeição
- Aumentar a conscientização na comunidade.
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 2022 não conseguiu coletar dados suficientes no momento de enviar os 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 adicionar informações sobre quais projetos alcançaram as métricas ou revisaram as métricas.
Para saber mais, consulte a página de resultados da temporada de Documentos Google 2022, que inclui as propostas de projetos originais e estudos de caso completos para cada organização.
Como trabalhar com redatores técnicos
Na temporada do programa Documentos, os projetos devem recrutar, entrevistar, contratar e pagar redatores técnicos diretamente. Os redatores técnicos podem adicionar a si mesmos ao diretório mantido pela Season of Docs em nosso repositório do GitHub, mas a equipe da Season of Docs não analisa nem recomenda escritores técnicos.
Práticas recomendadas para a contratação de escritores técnicos para projetos de código aberto
Os projetos foram solicitados a compartilhar suas práticas recomendadas de recrutamento, contratação e trabalho com redatores técnicos. As principais recomendações foram:
Recrutamento
- Entrevistar menos candidatos e usar uma sessão de prática ao vivo, em vez de apenas analisar os currículos.
- Valorizar as habilidades de comunicação escrita e oral acima da proficiência na linguagem ou nas ferramentas do seu projeto
- Fazer perguntas diretas sobre como o redator técnico adquirirá qualquer conhecimento de domínio necessário para trabalhar com seu projeto
- Alguém com entusiasmo pela missão do seu projeto e que compartilha os principais valores de código aberto tem mais probabilidade de se manter motivada durante todo o projeto
- Esteja aberto a candidatos de todo o mundo, porque uma diversidade de pontos de vista e origens ajudará seu projeto, mas 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
Vagas
- Use um contrato que defina claramente as entregas, calendários de pagamentos e compromissos de tempo específicos
- Se o seu projeto tiver muitas incógnitas, inclua um marco para descoberta ou pesquisa separado da criação da documentação
Coordenação e comunicação
- Mantenha as decisões de gravação de registro de uma reunião para tornar mais fácil para todos que trabalham no projeto entender o contexto e as próximas etapas.
- Esclareça qual comunicação é esperada 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 "por quê" e não apenas "o quê"
- Conecte seus escritores técnicos com a comunidade mais ampla para dar a eles 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 para o qual toda a comunidade possa contribuir
- A revisão da documentação leva pelo menos o mesmo tempo e é tão intensiva quanto a revisão do código. Certifique-se de permitir tempo suficiente para ela
Algumas recomendações foram editadas e condensadas para maior clareza.
Assim como no programa de 2021, a maioria dos redatores técnicos da Temporada de Documentos Google de 2022 se candidatou diretamente às organizações com que trabalharam.
Problemas comuns ao trabalhar com redatores técnicos
Menos projetos relataram problemas de trabalho com os redatores técnicos no programa de 2022. A incapacidade dos redatores técnicos de concluir o programa foi o maior problema devido a doenças, trabalhar em tempo integral ou não cumprir o compromisso de tempo.
Um projeto relatou 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 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
Em maio, agosto e novembro de 2023, vamos enviar três pesquisas de acompanhamento aos participantes de 2022. Atualizaremos esta seção com os resultados à medida que eles forem recebidos.
Perguntas futuras
Como sempre, quanto mais aprendemos sobre a documentação em 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 linguagem e documentação
- Analisar projetos de documentação para descobrir se podem ser generalizados em modelos compartilháveis
- Desenvolver uma rubrica para entrevistar escritores técnicos em projetos de código aberto
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.