Fase atual:
O programa "Season of Docs" de 2021 terminou em 14 de dezembro de 2021. Consulte
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: 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 cada vegetal em conserva, em quantidades que variam de um único pepino filho a contêineres de rabanetes.
Autores: opcional: liste os autores do estudo de caso. Use os nomes de usuário se solicitado.
Resumo da proposta/declaração de problema
Que problema você estava tentando resolver com uma documentação nova ou aprimorada? 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ê criou sua proposta para a Temporada de documentos? Qual processo sua organização usou para decidir sobre uma ideia? Como você pediu e incorporou o feedback?
O GloriousPickle PickleDocs SIG ouviu sobre o programa Season of Docs por meio de um tweet do Open Source Programs Office do Google. O SIG discutiu o programa na 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ê fez a estimativa do trabalho? Houve despesas inesperadas? Você acabou gastando menos do que o valor do prêmio? Você tinha fundos fora da Temporada dos Documentos 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 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 foi ajudar nosso redator técnico a alugar um ponto de acesso Wi-Fi, porque ele estava em uma área afetada por incêndios florestais e perdeu o acesso à Internet em casa. Também enviamos menos camisetas do que planejamos para os participantes, então isso se equilibrou.
Além disso, decidimos compensar um colaborador do GloriousPickle, @Piccalily, que já foi um editor profissional em sua vida não-picles, para ajudar na revisão e ediçã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 (PickleDocs SIG)
- @Piccalily (editora de cópia)
- @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 da 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 entrou na chamada quinzenal do PickleDocs SIG e falou sobre o projeto conosco, fazendo várias sugestões valiosas que foram incorporadas à 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 era sobreposto por apenas algumas horas com a maioria dos membros do PickleDocs SIG, enviamos uma chamada em nosso fórum de discussão para os Picklers que estavam no fuso horário de Sam e 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. O @GloriousPicklePat também se ofereceu para ajudar Sam a entender a arquitetura subjacente da ferramenta e possíveis mensagens de erro da API, e forneceu ajuda com GitHub e 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 se move tão rapidamente que perdemos as conversas por causa do limite contínuo de arquivamento), aprendemos que devemos manter uma lista de perguntas em execução em um documento compartilhado (usamos um documento Google compartilhado). 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.
Foi um prazer trabalhar com Sam e, além de atualizar a documentação do GloriousPickle, ele se tornou um ávido usuário do pickler.
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 que o programa Temporada do Documentos anunciasse as organizações participantes, os membros do SIG do PickleDocs 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 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 de 2021, Sam e o SIG PickleDocs se reuniram e elaboraram um cronograma aproximado:
| Fase | Concluída por |
|---|---|
| Revisar auditoria de documentos | 7 de maio |
| Caso de uso do registro de atrito 3 | 14 de maio |
| Analisar os registros de problemas com @GloriousPicklePat e @BBChips e responder às consultas | 28 de maio |
| Primeiro rascunho do caso de uso 1 de documentos atualizados | 25 de junho |
| Rascunho do caso de uso 1 revisado por @GloriousPicklePat e @KimChiCook | 2 de julho |
| Primeiro rascunho do caso de uso 2 de 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 analisado por @Dillicious e @KimChiCook | 16 de julho |
| Todas as consultas respondidas em todos os casos de uso | 30 de julho |
| A maior parte do PickleDocs SIG estava de férias entre 1o 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 |
| Revisão de texto e ortografia de novos documentos | 17 de setembro |
| O status de rascunho dos documentos foi removido, e os documentos foram lançados oficialmente | 28 de setembro |
| Processo para atualizar a documentação criada | 1o 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 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.
Criamos uma folha de referência para colaboradores novos no GitHub para ajudar a usar nossos processos e ferramentas, mas, depois de analisar os recursos disponíveis, conseguimos bifurcar a folha 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? As 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 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 acompanhar 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.
Acreditamos que essa nova documentação fez a diferença para que novos colaboradores pudessem adicionar ao banco de dados de ingredientes do GloriousPickle. Um novo colaborador mencionou no comentário do PR que já 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 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 da Temporada do Documentos e consideramos que foi 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 era que muitos termos e siglas relacionados a picles não eram familiares para alguém que entrasse em nosso projeto e não tivesse experiência em picles. No entanto, Sam fez questão de manter uma lista de todos os termos desconhecidos e definiu por meio de uma pesquisa própria, além de pedir 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 em conservação ou experiência com o GitHub, como escritor técnico experiente, eles se sentiam à vontade para mergulhar em uma nova área de assunto, fazer perguntas e fazer pesquisas. 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 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 Sam na Temporada de Documentos no GitHub, nos sentimos confiantes para trabalhar com eles 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 assistir a alguns tutoriais, se atualizaram rapidamente. No início, Sam estava preocupado com a quantidade de feedback que poderia receber da comunidade e como incorporá-lo, mas o modelo de "consenso aproximado" da nossa comunidade ("o consenso é alcançado quando todos os problemas são resolvidos, mas não necessariamente acomodados") fez com que ele se sentisse confiante para lidar com as críticas usando sua experiência em redação 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 agradecer as seguintes pessoas e coisas:
- @Dillicious gostaria de agradecer ao parceiro e também à rádio hip hop de baixa fidelidade
- @KimChiChi gostaria de agradecer ao 할머니 por ensiná-lo 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 restante da equipe por aceitar sua saída
- @BBChips quer agradecer à melhor comida sem picles disponível, a Tunnock's Caramel Wafers
- @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!