Fase atual:
Os resultados foram anunciados. Consulte a
linha do tempo.
Use este exemplo para criar seu próprio relatório de estudo de caso.
PicklePlus: documentação da ferramenta de contribuição GloriousPickle
Organização ou projeto: Glorious Pickle link para o site principal da sua organização ou projeto aqui
Descrição da organização: GloriousPickle (versão atual 1.2.3, primeira versão lançada em 2009) é uma biblioteca licenciada pelo MIT para calcular facilmente a proporção perfeita de sal, açúcar, vinagre e especiarias para todos os vegetais que podem ser em conserva, em quantidades que variam de um único pepino pequeno a um caminhão de raiz-forte.
Autores: opcional: liste os autores do estudo de caso; use nomes de usuário, se solicitado
Resumo da proposta/declaração de problema
Qual problema você estava tentando resolver com a documentação nova ou melhorada? Link para a página da proposta no site do projeto, se possível.
Adicionar ingredientes ao banco de dados de ingredientes da ferramenta GloriousPickle é demorado e complicado, e a ferramenta não tem uma boa documentação. Muitos possíveis colaboradores não têm experiência com o uso do git ou com a criação de solicitações de pull. Isso significa que o GloriousPickle tem lacunas graves nos dados de ingredientes e torna nossa ferramenta menos útil. Ao melhorar a documentação para adicionar novos ingredientes, esperamos incentivar novos colaboradores e mais conservação.
Descrição do projeto
Criação da proposta
Como você elaborou sua proposta para o Temporada dos Documentos Google? Qual processo sua organização usou para decidir sobre uma ideia? Como você pediu e incorporou o feedback?
O SIG GloriousPickle PickleDocs soube do programa Google Season of Docs por um tweet do Open Source Programs Office do Google. O SIG discutiu o programa em sua reunião quinzenal e concordou em criar uma proposta. Dois membros do SIG (@KimChiCook e @Dillicious) se ofereceram para trabalhar no rascunho da proposta para revisão na próxima reunião.
Depois que o SIG do PickleDocs concordou com o rascunho da proposta, um e-mail foi enviado ao projeto mais amplo solicitando feedback. Quatorze membros da comunidade ofereceram feedback, incluindo @GloriousPicklePat, o mantenedor da API de adição de ingredientes. @GloriousPicklePat se ofereceu como recurso durante o programa.
Depois de discutir e incorporar o feedback recebido, a proposta foi enviada ao comitê diretor do projeto GloriousPickle para votação. Todos os cinco membros do GPPSC votaram +1 para enviar a proposta e a inscrição, e @VinegarViv concordou em ajudar a criar a conta do Open Collective necessária para participar do programa e supervisionar os pagamentos.
Orçamento
Inclua uma seção curta sobre seu orçamento. Como você estimou o trabalho? Houve despesas inesperadas? Você acabou gastando menos do que o valor do prêmio? Você alocou os fundos corretamente ou alguns itens orçados foram a mais/menos/desnecessários? Você teve outros fundos fora do Google Season of Docs que conseguiu usar?
Dois membros do SIG GloriousPickle PickleDocs trabalharam como redatores técnicos (um na Europa e outro na Argentina). Eles nos ajudaram a estimar o trabalho e encontrar orçamentos de projetos semelhantes, comparando o trabalho de proposta de rascunho que eles fizeram antes. Também tínhamos US$1.000 em patrocínios não restritos da nossa convenção PicklePals de 2019 que foram alocados para o projeto.
Uma despesa imprevista estava ajudando nosso redator técnico a alugar um ponto de acesso Wi-Fi, já que ele estava em uma área afetada por incêndios e perderam o acesso à Internet em sua casa. Também acabamos enviando menos camisetas para os participantes do que planejamos, então o jogo foi equilibrado.
Além disso, decidimos compensar uma colaboradora do GloriousPickle, @Piccalily (que já foi uma editora profissional em sua vida fora do pickle) para ajudar com a edição e a revisão da documentação criada pelo redator técnico.
Participantes
Quem trabalhou neste projeto (use nomes de usuário se solicitado pelos participantes)? Como você encontrou e contratou seu redator técnico? Como você encontrou outros voluntários ou participantes pagos? Quais funções eles tinham? Alguém desistiu? O que você aprendeu sobre recrutamento, comunicação e gerenciamento de projetos?
A equipe principal que trabalhou neste projeto foi:
- @Dillicious, @KimChiCook (SIG do PickleDocs)
- @Piccalily (copyeditor)
- @GherKen, @VinegarViv (ajuda para administradores, GPPSC)
- @BBChips, @GloriousPicklePat (especialistas no assunto)
- Sam Scribe (redator técnico)
Encontramos o Sam Scribe na lista do repositório do GitHub do Google Season of Docs. Achamos que a experiência dele (Sam trabalhou para uma revista de culinária e escreveu documentação para sites) combinava bem com nosso projeto. Sam participou da chamada quinzenal do SIG do PickleDocs e conversou sobre o projeto com a gente, fazendo várias sugestões valiosas que incorporamos à proposta. Também entramos em contato com outros dois redatores técnicos conhecidos pelas redes dos membros do SIG, mas nenhum deles estava disponível durante o período do programa.
Como o fuso horário de Sam só se sobrepunha por algumas horas com a maioria dos membros do SIG PickleDocs, enviamos uma chamada no nosso fórum de discussão para os Picklers que estavam no fuso horário de Sam e estavam familiarizados com o processo de adição de ingredientes. @BBChips se ofereceu para responder às perguntas de Sam e ajudar a encontrar outros especialistas, se necessário. @GloriousPicklePat também se ofereceu para ajudar Sam a entender a arquitetura subjacente da ferramenta e possíveis mensagens de erro da API, além de oferecer ajuda no GitHub e no git.
Infelizmente, no meio do programa, @VinegarViv teve que se afastar do projeto por motivos pessoais. O membro do GPPSC @GherKen se ofereceu para lidar com questões administrativas e de pagamento.
Depois de algumas perguntas perdidas (o GloriousPickle usa uma instância sem custo financeiro do Slack e, às vezes, a discussão avança tão rapidamente que perdemos conversas devido ao limite de arquivamento contínuo), aprendemos que devemos manter uma lista de perguntas em um documento compartilhado (usamos um documento compartilhado do Google). Os membros do SIG do PickleDocs verificavam isso antes de cada reunião e se certificavam de receber respostas antes do fim da reunião. Sam conseguiu entrar em contato diretamente com @BBChips para perguntas urgentes.
Ficamos muito felizes de trabalhar com Sam e Sam, além de atualizar a documentação do GloriousPickle, também se tornaram ávidos leitores.
Cronograma
Faça uma breve descrição do cronograma do seu projeto (indique a data de término estimada ou marcos intermediários se o projeto estiver em andamento).
Enquanto esperávamos o programa Google Season of Docs anunciar as organizações participantes, os membros do SIG PickleDocs fizeram uma pesquisa para encontrar trabalhos anteriores que achamos que seriam úteis para Sam. Ao longo de um mês, encontramos algumas notas de uma tentativa anterior de atualizar a documentação que havia parado. Também trabalhamos em partes dos materiais da auditoria de maturidade da documentação no repo do Google Open Docs.
Depois de recebermos a boa notícia de que fomos selecionados para a Temporada de documentos do Google, Sam e o SIG PickleDocs se reuniram e elaboraram um cronograma aproximado:
| Fase | Concluída por |
|---|---|
| Revisar auditoria de documentos | 7 de maio |
| Registro de atrito 3 casos de uso | 14 de maio |
| Analisar registros de atrito com @GloriousPicklePat e @BBChips, responder consultas | 28 de maio |
| Primeiro rascunho do caso de uso de documentos atualizados 1 | 25 de junho |
| Rascunho do caso de uso 1 revisado por @GloriousPicklePat e @KimChiCook | 2 de julho |
| Primeiro rascunho do caso de uso de documentos atualizados 2 | 2 de julho |
| Rascunho do caso de uso 2 analisado por @GloriousPicklePat e @Dillicious | 9 de julho |
| Primeiro rascunho do caso de uso de documentos atualizados 3 | 9 de julho |
| Rascunho do caso de uso 3 analisado por @Dillicious e @KimChiCook | 16 de julho |
| Todas as consultas respondidas em todos os casos de uso | 30 de julho |
| A maioria do SIG do PickleDocs estava de férias de 1º a 20 de agosto | -- |
| Começar a testar novos documentos na comunidade (publicados como rascunhos no site GloriousPickle) | 21 de agosto |
| Feedback de teste incorporado | 10 de setembro |
| Revisão de texto e ortografia de novos documentos | 17 de setembro |
| Status de rascunho de documentos removidos, documentos lançados oficialmente | 28 de setembro |
| Processo para atualizar a documentação criada | 1º de novembro |
| Este estudo de caso criou | 8 de novembro |
| Estudo de caso enviado | 16 de novembro |
No orçamento da proposta, estimamos que o redator técnico passaria de 10 a 15 horas por semana trabalhando no projeto. Sam registrou o tempo gasto e teve uma média de 11,5 horas por semana.
Resultados
O que foi criado, atualizado ou alterado? Inclua links para a documentação publicada, se disponível. Houve algum resultado na proposta que não foi criado? Liste-as também.
Três casos de uso principais foram documentados com guias completos de instruções para o usuário:
Como adicionar um novo ingrediente ao GloriousPickle
Como adicionar um ingrediente variante ao GloriousPickle
Como atualizar ou corrigir um ingrediente no GloriousPickle
Esses guias também incluem novos modelos de solicitação de pull para facilitar as contribuições.
Além disso, durante o projeto, Sam criou um pequeno glossário de termos que aprendeu, que também foi publicado no site do projeto GloriousPickle.
Adicionamos instruções para atualizar esses guias de instruções para o usuário no wiki do projeto.
Incluímos a criação de uma folha de referência para novos colaboradores no GitHub para ajudá-los a usar nossos processos e ferramentas, mas depois de analisar os recursos disponíveis, foi possível bifurcar a folha de referência de outro projeto.
Métricas
Quais métricas você escolheu para medir o sucesso do projeto? Você conseguiu coletar essas métricas? As métricas se correlacionaram bem ou mal com os resultados que você queria para o projeto? Suas métricas mudaram desde a proposta?
Na nossa proposta, propusemos duas métricas:
- número de solicitações de envio relacionadas a ingredientes
- número de solicitações de envio de novos colaboradores
No mês de setembro (o primeiro mês completo desde a publicação do rascunho da documentação), observamos um aumento de 5% nas solicitações de envio relacionadas a ingredientes (de 20 em agosto para 21 em setembro) e três novos colaboradores que fizeram quatro solicitações de envio no total (contra dois novos colaboradores que fizeram duas solicitações de envio em agosto). Planejamos monitorar essas métricas mensalmente.
A partir de 1º de janeiro, também vamos monitorar o número de colaboradores que fizeram mais de três contribuições no total, começando trimestralmente após a publicação da documentação.
Curiosamente, acreditamos que essa nova documentação fez a diferença ao permitir que novos colaboradores façam a adição ao banco de dados de ingredientes do GloriousPickle. Um novo colaborador mencionou no comentário do RP que já havia tentado antes, mas não havia concluído a atualização por não entender o processo.
Análise
O que deu certo? O que foi inesperado? Quais obstáculos ou contratempos você enfrentou? Você considera seu projeto bem-sucedido? Por que sim ou por que não? (Se for muito cedo para dizer, explique quando você espera poder julgar o sucesso do seu projeto.)
Estamos muito satisfeitos com o resultado do nosso projeto Google Season of Docs e considerá-lo um sucesso. A nova documentação é clara e útil, e já notamos um aumento no número de solicitações de mesclagem relacionadas a ingredientes e de novos colaboradores.
Também ficamos felizes que quase toda a comunidade do GloriousPickle participou, feedback sobre a proposta original e testando os novos documentos em rascunho.
Tivemos alguns obstáculos inesperados, mas ficamos felizes que os incêndios florestais no estado de Sam não causaram mais danos do que uma interrupção da Internet. Além disso, lamentamos a saída de @VinegarViv do projeto. Desejamos o melhor a ela e à família e esperamos encontrá-la novamente em breve.
Uma coisa que não percebemos até que Sam começou a trabalhar na documentação foi que muitos termos e acrônimos relacionados ao picles seriam desconhecidos para alguém que entrasse no projeto sem experiência com o assunto. No entanto, Sam fez questão de manter uma lista de todos os termos desconhecidos e os definiu por conta própria, pesquisando e pedindo explicações e referências aos membros da comunidade. Este glossário de picles vai ajudar muito a acolher mais pessoas na comunidade de picles no futuro.
Resumo
Em dois a quatro parágrafos, resuma sua experiência com o projeto. Destaque o que você aprendeu e o que faria de forma diferente no futuro. Que conselho você daria a outros projetos que tentam resolver um problema semelhante com a documentação?
Em uma palavra, nossa experiência foi incrível! Concluímos a documentação e nossas métricas parecem estar alinhadas às nossas metas.
Uma grande parte do sucesso desse projeto foi a sorte de trabalhar com nosso redator técnico, Sam Scribe. [Eu não escrevi isso, Sam] Embora Sam não tivesse experiência com o GitHub, como redator técnico experiente, ele se sentia à vontade para mergulhar em uma nova área de assunto, fazer perguntas e pesquisar. Sam rapidamente aprendeu não apenas nossas ferramentas de projeto (usamos um quadro Kanban para acompanhar o trabalho), mas também nossas piadas sobre picles. Estamos muito felizes por Sam ter descoberto o problema e por termos "engarrafado" ele na nossa comunidade.
Recomendamos que outros projetos:
- Mantenha suas propostas pequenas e gerenciáveis. Originalmente, queríamos incluir na proposta a documentação para usar nosso estimador com máquinas industriais de picles em lote e só a deixamos de fora porque um dos membros da nossa comunidade, que estava profundamente envolvido com máquinas de picles de código aberto, ia escrever a tese de doutorado durante o programa. Acabamos tendo trabalho mais do que suficiente para manter Sam ocupado.
- Use suas redes de contato ao procurar um redator técnico. Peça recomendações a todos na sua comunidade. Embora tenhamos encontrado o Sam no GitHub do Google Season of Docs, nos sentimos confiantes em trabalhar com ele porque conversamos com várias pessoas durante o período de inscrição.
- A comunidade recebe o redator técnico. Sam nos disse que a atitude entusiasmada dos GloriousPicklers facilitou a formulação de perguntas.
- Ajude o redator técnico a adquirir habilidades de código aberto. Sam nunca tinha usado o git antes, mas depois de passar por alguns tutoriais, ele se familiarizou rapidamente. No início, Sam estava preocupado com o possível feedback da comunidade e como incorporá-lo. No entanto, o modelo de "consenso aproximado" (""um consenso é alcançado quando todos os problemas são abordados, mas não necessariamente acomodado") deixou ele confiante para lidar com as críticas usando sua experiência em escrita técnica.
Apêndice
Se você tiver outros materiais que gostaria de vincular (por exemplo, se você criou um contrato para trabalhar com seu redator técnico que gostaria de compartilhar, ou modelos para seu projeto de documentação ou outros recursos de documentação abertos, você pode listar e vincular aqui). O apêndice também é um bom lugar para listar links para ferramentas ou recursos de documentação que você usou ou para adicionar agradecimentos ou reconhecimentos que não se encaixam nas seções acima.
Agradecimentos
Nossa equipe gostaria de reconhecer as seguintes pessoas e coisas:
- @Dillicious gostaria de agradecer ao parceiro e também à rádio hip-hop de baixa fidelidade
- @KimChiCook gostaria de agradecer a 할머니 por ensinar a fazer picles
- @Piccalily gostaria de agradecer ao Chicago Manual of Style Online
- @GherKen quer agradecer aos três filhos por comerem todos os picles que ele faz
- @VinegarViv gostaria de agradecer ao resto da equipe por terem acomodado a deixar a função
- @BBChips gostaria de agradecer ao melhor alimento não-conservado disponível, os biscoitos de caramelo Tunnock's
- @GloriousPicklePat gostaria de agradecer ao PickleDocs SIG por assumir este projeto
- Sam Scribe gostaria de agradecer a toda a comunidade GloriousPickle, mas especialmente aos Picklers que lhes enviaram potes de conservas durante a escassez de potes no verão de 2021, iniciando-os no caminho para muitos picles deliciosos!