Fase atual:
a temporada de 2021 do programa Documentos foi encerrada em 14 de dezembro de 2021. Consulte o
cronograma.
Use este exemplo para criar seu próprio relatório de estudo de caso.
PicklePlus: documentando a 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, primeiro lançamento em 2009) é uma biblioteca licenciada pelo MIT para calcular facilmente a proporção perfeita de sal, açúcar, vinagre e temperos para cada vegetal em conserva possível, em quantidades que vão de um único pepino solitário a carga de rabanetes em contêineres.
Autores: opcional: liste os autores do estudo de caso e use nomes de usuário se solicitado
Declaração de problema/Resumo da proposta
Que problema você estava tentando resolver com uma 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. Além disso, a ferramenta não tem uma boa documentação. Muitos possíveis colaboradores não têm experiência com git ou com solicitações de envio. Isso significa que o GloriousPickle tem sérias lacunas 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 conservadores!
Descrição do projeto
Criar a proposta
Como você elaborou sua proposta para a temporada dos Documentos Google? Qual processo sua organização usou para decidir sobre uma ideia? Como você solicitou e incorporou feedback?
O SIG GloriousPickle PickleDocs ouviu falar sobre o programa Season of Docs por meio de 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 da SIG (@KimChiCook e @Dillicious) se ofereceram para trabalhar no rascunho da proposta e analisá-lo na próxima reunião.
Depois que o SIG da PickleDocs concordou com o rascunho da proposta, um e-mail foi enviado para o projeto como um todo solicitando feedback. Quatorze membros da comunidade ofereceram feedback, incluindo @GloriousPicklePat, o mantenedor da API de adição de ingredientes. @GloriousPicklePat se ofereceu para ser um 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 da GPPSC votaram em +1 para enviar a proposta e a inscrição, e @VinegarViv concordou em ajudar a criar a conta Open Collective necessária para participar do programa e supervisionar os pagamentos.
Orçamento
Inclua uma pequena seção sobre seu orçamento. Como você estimou o trabalho? Houve alguma despesa inesperada? Você gastou menos do que o prêmio? Você tinha outros fundos fora da Season of Docs que conseguiu usar?
Dois membros do GloriousPickle PickleDocs SIG trabalharam como redatores técnicos (um na Europa e outro na Argentina). Eles nos ajudaram a estimar o trabalho e encontrar orçamentos de projeto semelhantes, comparando o rascunho da proposta que ele já havia feito antes. Também tínhamos US$1.000 restantes em dinheiro de patrocínio irrestrito da convenção PicklePals de 2019 que alocamos 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 florestais e perdeu o acesso à Internet em casa. Também acabamos enviando menos camisetas para os participantes do que havíamos planejado, então o equilíbrio.
Além disso, decidimos compensar uma colaboradora do GloriousPickle, @Piccalily (que já foi editora profissional durante sua vida profissional) para ajudar na edição de textos e na revisão da documentação criada pelo redator técnico.
Participantes
Quem trabalhou no 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? Que funções eles tinham? Alguém saiu? O que você aprendeu sobre recrutamento, comunicação e gerenciamento de projetos?
A equipe principal que trabalhava no projeto foi:
- @Dillicious, @KimChiCook (PickleDocs SIG)
- @Piccalily (copyeditor)
- @GherKen, @VinegarViv (ajuda para admins, GPPSC)
- @BBChips, @GloriousPicklePat (especialistas no assunto)
- Sam Scribe (escritor técnico)
Encontramos Sam Scribe na lista de repositório da temporada de documentos do GitHub (em inglês). Achamos que a experiência deles (Sam tinha trabalhado para uma revista de culinária e redação de documentação para sites) combinava bem com nosso projeto. Sam entrou na chamada quinzenal da PickleDocs SIG e conversou sobre o projeto conosco, fazendo várias sugestões valiosas que incorporamos à proposta. Também entramos em contato com dois outros redatores técnicos conhecidos por meio de nossas redes de membros do SIG, mas nenhum deles estava disponível durante o período do programa.
Como o fuso horário de Sam se sobrepôs em apenas algumas horas com a maioria dos membros do PickleDocs SIG, enviamos uma chamada em nosso fórum de discussão para Picklers que estavam no fuso horário de Sam e familiarizados com o processo de adição de ingredientes. A @BBChips se ofereceu para responder a perguntas para Sam e ajudar a encontrar outros especialistas conforme 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 fornecer ajuda do GitHub e do Git.
Infelizmente, no meio do programa, @VinegarViv precisou se afastar do projeto por motivos pessoais. @GherKen, membro da GPPSC, entrou em contato para responder a perguntas administrativas e de pagamento.
Depois de algumas perguntas perdidas (GloriousPickle usa uma instância sem custo financeiro do Slack e, ocasionalmente, a discussão avança tão rapidamente que perdemos conversas por causa do limite de arquivos contínuos), aprendemos que devemos manter uma lista de perguntas em execução em um documento compartilhado (usamos um Documento Google compartilhado). Os membros da PickleDocs SIG verificavam as informações antes de cada reunião e encontravam as respostas antes do final. Samuel conseguiu fazer um ping direto na @BBChips para perguntas urgentes.
Ficamos muito felizes em trabalhar com Sam e Sam. Além de atualizar a documentação do GloriousPickle, também se tornou um picante ávido.
Cronograma
Apresente uma breve visão geral 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 Season of Docs para anunciar as organizações participantes, os membros da PickleDocs SIG fizeram uma pesquisa por qualquer trabalho anterior que pensávamos que seria útil para Sam. Ao longo de um mês, encontramos algumas notas de uma iniciativa anterior para atualizar a documentação que parou, e também trabalhamos em partes dos materiais de auditoria de maturidade da documentação no repositório do Google opendocs.
Assim que recebemos a boa notícia de que fomos selecionados para a Temporada de Documentos do Google de 2021, Sam e o SIG da PickleDocs se encontraram e definiram um cronograma bruto:
| Etapa | Concluída por |
|---|---|
| Revise a auditoria de documentos | 7 de maio |
| Casos de uso do registro de atrito 3 | 14 de maio |
| Analise os registros de atrito com @GloriousPicklePat e @BBChips e responda a 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 2 dos documentos atualizados | 2 de julho |
| Rascunho do caso de uso 2 revisado 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 revisado por @Dillicious e @KimChiCook | 16 de julho |
| Todas as consultas respondidas para todos os casos de uso | 30 de julho |
| A maior parte do PickleDocs SIG ficou de férias entre 1 e 20 de agosto | -- |
| Começar a testar novos documentos na comunidade (documentos publicados como rascunhos no site GloriousPickle) | 21 de agosto |
| Feedback de teste incorporado | 10 de setembro |
| Edição e revisão de novos documentos | 17 de setembro |
| Status de rascunho dos documentos removidos, lançamento oficial dos documentos | 28 de setembro |
| Processo de atualização da documentação criada | 1o de novembro |
| Este estudo de caso criou | 8 de novembro |
| Estudo de caso enviado | 16 de novembro |
Em nosso orçamento da proposta, estimamos que o redator técnico gastaria de 10 a 15 horas por semana trabalhando em nosso projeto. Sam manteve registros do tempo gasto e fez 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íveis. Houve alguma entrega na proposta que não foi criada? Liste-os também.
Três casos de uso principais foram documentados com guias de instruções completos do 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 incluíram novos modelos de solicitações de envio para facilitar as contribuições.
Além disso, durante o projeto, Sam criou um pequeno glossário de termos aprendidos em Pickle, que também foi publicado no site do projeto GloriousPickle.
Adicionamos instruções para atualizar esses guias de instruções do usuário na página wiki do projeto.
Incluímos a criação de uma folha de referência para colaboradores novos no GitHub para ajudá-los a usar nossos processos e ferramentas, mas depois de analisar os recursos disponíveis, pudemos 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?
Em nossa proposta, propomos 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 da documentação de rascunho), vimos um aumento de 5% nas solicitações de envio relacionadas a ingredientes (de 20 em agosto para 21 em setembro) e tivemos três novos colaboradores que fizeram quatro solicitações de envio no total (em comparação a dois novos que fizeram duas solicitações de envio em agosto). Planejamos monitorar essas métricas mensalmente.
A partir de 1o de janeiro, também rastrearemos 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 fossem adicionados ao banco de dados de ingredientes GloriousPickle. Um novo colaborador mencionou no comentário de seu RP que ele havia tentado antes, mas não havia concluído a atualização porque não entendia 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 quê? Se for muito cedo para dizer, explique quando você espera ser capaz de julgar o sucesso do seu projeto.
Estamos muito satisfeitos com o resultado do nosso projeto Season of Docs e consideramos um sucesso. A nova documentação é clara e útil, e já vimos algum crescimento no número de solicitações de envio relacionadas a ingredientes e no número de solicitações de novos colaboradores.
Também ficamos felizes com a participação de quase toda a comunidade GloriousPickle, enviando feedback sobre a proposta original e testando os novos documentos na forma de rascunho.
Enfrentamos alguns obstáculos inesperados. Agradecemos que os incêndios florestais no estado de Sam não causaram mais danos do que uma interrupção da Internet. Além disso, sentimos muito por perder @VinegarViv do projeto. Desejamos muito sucesso a ela e à sua família e esperamos vê-la novamente em breve.
Uma coisa que não percebemos até que Sam começou a trabalhar na documentação era quantos termos e acrônimos relacionados a picles não eram familiares para alguém que chegava ao nosso projeto sem experiência em pickle. No entanto, Sam decidiu manter uma lista de todos os termos desconhecidos e os definiu por meio de pesquisas próprias e pedindo explicações e referências aos membros da comunidade. Este Glossário de Pickle será uma grande ajuda para receber mais pessoas na comunidade de pickle no futuro.
Resumo
Em dois a quatro parágrafos, resuma sua experiência com o projeto. Destaque o que você aprendeu e o que escolheria fazer diferente no futuro. Que conselho você daria para outros projetos que estão tentando resolver um problema semelhante com a documentação?
Resumindo, nossa experiência foi piceta! Conseguimos entregar a documentação, e nossas métricas parecem estar alinhadas às nossas metas.
Uma grande parte do sucesso desse projeto foi a sorte que tivemos em trabalhar com nosso redator técnico, Sam Scribe. [Eu não escrevi isso — Sam] Embora Sam não tenha formação em conserva ou experiência com GitHub, como redator técnico experiente, ele se sentia à vontade para mergulhar em uma nova área temática, fazer perguntas e fazer pesquisas. Sam pegou rapidamente não apenas nossas ferramentas de projeto (usamos um quadro kanban para acompanhar o trabalho), mas também nossas piadas com muitas coisas! Estamos muito felizes que Sam pegou o inseto em conserva e que nós o "engarrafamos" na nossa comunidade.
Aconselhamos outros projetos a:
- Mantenha suas propostas pequenas e gerenciáveis. (Inicialmente, queríamos incluir documentação para usar nosso estimador com máquinas de decapagem de lotes industrial em nossa proposta, e só deixamos de fora porque um dos membros da nossa comunidade profundamente envolvidos profundamente em máquinas de picles de código aberto escreveria sua tese de doutorado durante o programa.) Acabamos tendo trabalho mais do que suficiente para manter Sam ocupado.
- Aproveite suas redes ao procurar um redator técnico. Peça recomendações a todos na sua comunidade. Embora tenhamos encontrado Sam na Temporada de Documentos GitHub, nos sentimos confiantes de trabalhar com eles porque conversamos com várias pessoas durante o período de inscrição.
- Boas-vindas ao seu redator técnico em sua comunidade! Sam nos contou que a atitude entusiasmada dos GloriousPicklers facilitou a realização de perguntas.
- Ajude seu escritor técnico a adquirir habilidades de código aberto. Sam nunca havia usado o git antes, mas depois de ver alguns tutoriais eles aprenderam rapidamente. No início, Sam estava preocupado com o feedback que receberia da comunidade e como incorporá-lo, mas o modelo de "consenso aproximado" da nossa comunidade ("consenso é alcançado quando todos os problemas são abordados, mas não necessariamente acomodados") deixou Sam confiante em abordar as críticas usando sua experiência técnica de redação.
Apêndice
Se quiser criar um link para outros materiais, por exemplo, se você criou um contrato para trabalhar com seu redator técnico e gostaria de compartilhar, modelos para seu projeto de documentação ou outros recursos de documentação abertos, liste-os aqui. O Apêndice também é um bom lugar para listar links para ferramentas ou recursos de documentação que você usou, ou um local para adicionar agradecimentos ou agradecimentos 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 dela e também à rádio de hip hop de baixa fidelidade
- @KimChiCook gostaria de agradecer a 할머니 por ensinar a ele a conserva
- @Piccalily gostaria de agradecer ao Chicago Manual of Style Online
- @GherKen gostaria de agradecer aos três filhos por comer todos os picles que ele pode fazer
- A @VinegarViv gostaria de agradecer ao restante da equipe por terem gostado da saída
- O @BBChips gostaria de agradecer a melhor comida disponível sem picles, o Tunnock's Caramel Wafers
- @GloriousPicklePat gostaria de agradecer à PickleDocs SIG por assumir este projeto
- Sam Scribe gostaria de agradecer a toda a comunidade GloriousPickle, mas especialmente os Picklers que enviaram potes de conserva durante a escassez de potes no verão de 2021, preparando-os para a estrada com muitos picles deliciosos.