Fase atual:
resultados 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, primeiro lançamento 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 em conserva, em quantidades que vão de um único pepino solitário a carga de rabanetes.
Autores: opcional: liste os autores do estudo de caso. Use nomes de usuário se solicitado
Declaração de problema/Resumo da proposta
Qual problema você estava tentando resolver com uma documentação nova ou aprimorada? Adicione um link para a página da proposta no site do seu 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 colaboradores em potencial não têm experiência com o uso do git ou de solicitações de envio. Isso significa que o GloriousPickle tem graves lacunas nos nossos dados de ingredientes e torna nossa ferramenta menos útil. Ao aprimorar 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 a temporada de Documentos Google? Qual processo sua organização usou para tomar uma decisão sobre uma ideia? Como você solicitou e incorporou feedback?
O SIG do GloriousPickle PickleDocs ouviu falar sobre o programa Season of Docs do Google por meio de um tweet do Escritório de Programas de Código Aberto 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 a ser analisado 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 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 do GPPSC votaram em +1 para enviar a proposta e a inscrição, e a @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 do subsídio? Você alocou os fundos corretamente ou houve um orçamento para mais/menos/desnecessário? Você tinha outros fundos fora da temporada de Documentos Google?
Dois membros da SIG GloriousPickle PickleDocs já 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 já haviam feito antes. Também tínhamos US$1.000 restantes em dinheiro de patrocínio irrestrito da nossa 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 e perderia o acesso à Internet em casa. Também acabamos enviando menos camisetas para os participantes do que planejávamos, então foi equilibrado.
Além disso, decidimos compensar @Piccalily, uma colaboradora do GloriousPickle, que já foi editora profissional em uma vida sem muito palhaço, para ajudar na edição de textos e na revisão da documentação criada pelo redator técnico.
Participantes
Quem trabalhou neste projeto (use nomes de usuário se os participantes pedirem)? 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 neste projeto foi:
- @Dillicious, @KimChiCook (SIG de PickleDocs)
- @Piccalily (copyeditor)
- @GherKen, @VinegarViv (ajuda para admins, GPPSC)
- @BBChips, @GloriousPicklePat (especialistas no assunto)
- Sam Scribe (escritor técnico)
Encontramos Sam Scribe na lista do repositório da temporada de documentos do Google no GitHub (em inglês). Achamos que a experiência deles (Sam trabalhou para uma revista de culinária, bem como escrevendo documentação para sites) combinou bem com nosso projeto. Sam entrou na chamada quinzenal do 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 ao da 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. O @BBChips se ofereceu para responder a perguntas e ajudá-lo a encontrar outros especialistas conforme necessário. @GloriousPicklePat também foi voluntário 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. @GherKen, membro do GPPSC, ligou para questões 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 arquivamento contínuo), 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 verificaram a estrutura antes de cada reunião e se certificaram de receber as respostas antes do final da reunião. Sam conseguiu dar um ping direto no @BBChips em caso de 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 ávido picador!
Cronograma
Dê uma breve visão geral do cronograma do projeto (indique a data de término estimada ou marcos intermediários se o projeto estiver em andamento).
Enquanto esperávamos que o programa Season of Docs do Google anunciasse as organizações participantes, os membros do PickleDocs SIG pesquisaram qualquer trabalho anterior que julgamos ser útil para Sam. Ao longo de um mês, encontramos algumas notas de um esforço anterior para atualizar a documentação que havia paralisada, 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, Sam e o SIG de PickleDocs se reuniram e definiram um cronograma aproximado:
| Etapa | Concluída por |
|---|---|
| Revisar 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 de documentos atualizados 2 | 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 em todos os casos de uso | 30 de julho |
| A maioria do PickleDocs SIG estava de férias entre 1o e 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 |
| Edição e revisão de novos documentos | 17 de setembro |
| Status de rascunho de documentos removidos, lançamento oficial dos documentos | 28 de setembro |
| Processo de atualização da documentação criado | 1o de novembro |
| Este estudo de caso criou | 8 de novembro |
| Estudo de caso enviado | 16 de novembro |
Em nosso orçamento de 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 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í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ção de envio para facilitar as contribuições.
Além disso, durante o projeto, Sam criou um pequeno glossário de Pickle com termos que eles aprenderam e que também foi publicado no site do projeto GloriousPickle.
Adicionamos instruções para atualizar esses guias de instruções do usuário no wiki do nosso 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, conseguimos 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, apresentamos 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), tivemos um aumento de 5% nas solicitações de envio relacionadas a ingredientes (de 20 em agosto para 21 em setembro), além de 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). Pretendemos acompanhar 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, a partir de trimestres 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 do RP que ele havia tentado antes, mas não concluiu a atualização por não entender o processo.
Análise
O que deu certo? O que foi inesperado? Que 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 Google Season of Docs e o consideramos um sucesso. A nova documentação é clara e útil, e já vimos um aumento no número de solicitações de envio relacionadas a ingredientes e de novos colaboradores.
Também ficamos felizes com a participação de quase toda a comunidade do GloriousPickle, enviando feedback sobre a proposta original e testando os novos documentos em formato de rascunho.
Enfrentamos alguns obstáculos inesperados. Agradecemos que os incêndios no estado de Sam não causaram mais danos do que uma interrupção na Internet! Lamentamos por ter perdido @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 foi quantos termos e acrônimos relacionados a picles não estariam familiarizados para alguém que entrava em nosso projeto sem experiência em conserva. No entanto, Sam fez questão de 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 acolher 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. Qual conselho você daria a outros projetos que tentam resolver um problema semelhante com a documentação?
Resumindo, nossa experiência foi muito pegajosa! Conquistamos nossas entregas de documentação e nossas métricas parecem estar alinhadas com nossos objetivos.
Uma grande parte do sucesso desse projeto foi nossa sorte de trabalhar com nosso redator técnico, Sam Scribe. [Não escrevi isso — Sam] Embora Sam não tenha experiência em picles ou experiência com GitHub, como escritor técnico experiente, eles se sentiam à vontade para mergulhar em um novo assunto, fazer perguntas e fazer pesquisas. Sam rapidamente pegou não apenas nossas ferramentas de projeto (usamos um quadro kanban para acompanhar o trabalho), mas também nossas piadas picantes! Estamos muito felizes que Sam pegou o inseto e que os "engarrafamos" em nossa comunidade.
Recomendamos que outros projetos:
- Mantenha suas propostas pequenas e gerenciáveis. (Inicialmente, queríamos incluir a documentação para usar nosso estimador com máquinas de conservação em lotes industrial em nossa proposta, e só a deixamos de fora porque um dos membros da nossa comunidade profundamente envolvido em máquinas de picles de código aberto iria escrever 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 no GitHub a temporada do Google Docs, nos sentimos confiantes para trabalhar com eles porque conversamos com várias pessoas durante o período de inscrição.
- Dê as boas-vindas ao seu redator técnico em sua comunidade! Sam informou que a atitude entusiasmada dos GloriousPicklers facilitou a realização de perguntas.
- Ajude seu escritor técnico a desenvolver 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 a quantidade de feedback que receberia da comunidade e como incorporá-lo, mas o modelo de "consenso aproximado" ("o consenso é alcançado quando todos os problemas são abordados, mas não necessariamente acomodados") deixou Sam confiante para lidar com as críticas usando sua experiência técnica de escrita.
Apêndice
Se você tiver outros materiais que queira incluir no link, por exemplo, caso tenha criado um contrato de trabalho com seu redator técnico que gostaria de compartilhar, modelos para seu projeto de documentação ou outros recursos de documentação abertos, liste e vincule aqui. O Apêndice também é um bom lugar para listar links para ferramentas ou recursos de documentação que você usou ou um lugar para agradecer ou agradecer que não se encaixa nas seções acima.
Agradecimentos
Nossa equipe gostaria de agradecer às seguintes pessoas:
- @Dillicious quer agradecer ao parceiro e também à rádio de hip hop de baixa fidelidade
- @KimChiCook quer agradecer ao 할머니 por ensinar a conservar
- @Piccalily gostaria de agradecer ao Manual de estilo on-line de Chicago
- @GherKen gostaria de agradecer aos três filhos dele por comer todos os picles que ele pode fazer
- @VinegarViv gostaria de agradecer ao restante da equipe por ter acomodado a saída
- @BBChips quer agradecer à melhor comida não à base de picles disponível, o Tunnock's Caramel Wafers
- @GloriousPicklePat gostaria de agradecer ao SIG de PickleDocs por assumir este projeto
- Sam Scribe gostaria de agradecer a toda a comunidade GloriousPickle, mas especialmente os Picklers que enviaram potes de conservas durante a escassez de potes no verão de 2021, iniciando a viagem com muitos picles deliciosos!