Current phase:
The 2021 Season of Docs program finished on December 14, 2021. See
timeline.
Use this example to help you create your own case study report.
PicklePlus: Documenting The GloriousPickle Contribution Tool
Organization or Project: Glorious Pickle link to the main site of your organization or project here
Organization Description: GloriousPickle (current version 1.2.3, first release in 2009) is an MIT-licensed library for easily calculating the perfect ratio of salt, sugar, vinegar, and spices for every possible pickleable vegetable, in quantities ranging from a single solitary baby cucumber to container-shiploads of radishes.
Authors: optional: list authors of the case study; use usernames if requested
Problem Statement/Proposal Abstract
What problem were you trying to solve with new or improved documentation? Link to the proposal page on your project site, if possible.
Adding ingredients to the GloriousPickle tool ingredient database is time-consuming and complicated, and the tool does not have good documentation. Many would-be contributors do not have experience using git or making pull requests. This means GloriousPickle has serious gaps in our ingredient data, and makes our tool less useful. By improving the documentation for adding new ingredients, we hope to encourage new contributors and more pickling!
Project Description
Creating the proposal
How did you come up with your Season of Docs proposal? What process did your organization use to decide on an idea? How did you solicit and incorporate feedback?
The GloriousPickle PickleDocs SIG heard about the Season of Docs program through a tweet from Google's Open Source Programs Office. The SIG discussed the program at their biweekly meeting, and agreed to create a proposal. Two members of the SIG (@KimChiCook and @Dillicious) volunteered to work on the draft proposal for review at the next meeting.
Once the PickleDocs SIG agreed on the proposal draft, an email was sent to the wider project asking for feedback. Fourteen community members offered feedback, including @GloriousPicklePat, the maintainer of the ingredient-adding API. @GloriousPicklePat volunteered to be a resource during the program.
After discussing and incorporating the feedback received, the proposal was sent to the GloriousPickle Project Steering Committee for a vote. All five members of the GPPSC voted +1 to submitting the proposal and application, and @VinegarViv agreed to help creating the Open Collective account required to participate in the program and oversee payments.
Budget
Include a short section on your budget. How did you estimate the work? Were there any unexpected expenses? Did you end up spending less than the grant award? Did you have other funds outside of Season of Docs that you were able to use?
Two members of the GloriousPickle PickleDocs SIG have worked as technical writers (one in Europe, and one in Argentina). They helped us estimate the work and find similar project budgets, comparing the draft proposal work they'd done before. We also had US$1000 left over in unrestricted sponsorship money from our 2019 PicklePals convention that we allocated to the project.
An unforeseen expense was helping our technical writer rent a wifi hotspot, as they were in an area affected by wildfires and lost internet access at their home. We also ended up sending out fewer t-shirts to participants than we planned, so it balanced out.
In addition, we decided to compensate a GloriousPickle contributor, @Piccalily (who was once a professional copyeditor in her non-pickle life) to help with copyediting and proofreading the documentation created by the technical writer.
Participants
Who worked on this project (use usernames if requested by participants)? How did you find and hire your technical writer? How did you find other volunteers or paid participants? What roles did they have? Did anyone drop out? What did you learn about recruiting, communication, and project management?
The core team working on this project was:
- @Dillicious, @KimChiCook (PickleDocs SIG)
- @Piccalily (copyeditor)
- @GherKen, @VinegarViv (admin help, GPPSC)
- @BBChips, @GloriousPicklePat (subject-matter experts)
- Sam Scribe (technical writer)
We found Sam Scribe through the Season of Docs GitHub repository list. We thought their experience (Sam had worked for a culinary magazine as well as writing documentation for websites) matched well with our project. Sam joined the PickleDocs SIG biweekly call and talked through the project with us, making several very valuable suggestions that we incorporated into the proposal. We also reached out to two other technical writers known to us through our SIG member's networks, but neither were available during the timespan of the program.
Because Sam's time zone only overlapped by a few hours with most of the members of the PickleDocs SIG, we sent out a call in our discussion forum for Picklers who were in Sam's time zone and familiar with the ingredient-adding process. @BBChips volunteered to answer questions for Sam and to help them find other experts as needed. @GloriousPicklePat also volunteered to help Sam understand the underlying architecture of the tool and possible error messages from the API, and provided GitHub and git help.
Unfortunately, midway through the program @VinegarViv had to step back from the project for personal reasons. GPPSC member @GherKen stepped up to handle administrative and payment questions.
After some missed questions (GloriousPickle uses a free Slack instance and occasionally the discussion moves so quickly that we lose conversations because of the rolling archive limit) we learned that we should keep a list of running questions in a shared document (we used a shared Google Doc). The PickleDocs SIG members checked it before each meeting and made sure to get answers before the end of the meeting. Sam was able to ping @BBChips directly for urgent questions.
We were very happy working with Sam and Sam, in addition to updating the GloriousPickle documentation, has become an avid pickler themselves!
Timeline
Give a short overview of the timeline of your project (indicate estimated end date or intermediate milestones if project is ongoing).
While we waited for the Season of Docs program to announce participating organizations, the PickleDocs SIG members did a search for any previous work that we thought would be useful to Sam. Over the course of a month, we found some notes from an earlier effort to update the documentation that had stalled, and we also worked through parts of the documentation maturity audit materials in the Google opendocs repo.
Once we got the good news that we were selected for the 2021 Season of Docs, Sam and the PickleDocs SIG met and worked out a rough schedule:
| Stage | Completed By |
|---|---|
| Review docs audit | 7 May |
| Friction log 3 use cases | 14 May |
| Review friction logs with @GloriousPicklePat and @BBChips, answer queries | 28 May |
| First draft of updated docs use case 1 | 25 June |
| Use case 1 draft reviewed by @GloriousPicklePat & @KimChiCook | 2 July |
| First draft of updated docs use case 2 | 2 July |
| Use case 2 draft reviewed by @GloriousPicklePat & @Dillicious | 9 July |
| First draft of updated docs use case 3 | 9 July |
| Use case 3 draft reviewed by @Dillicious & @KimChiCook | 16 July |
| All queries answered on all use cases | 30 July |
| Most of PickleDocs SIG was on vacation Aug 1-20 | -- |
| Begin testing of new docs in community (docs published as drafts on GloriousPickle site) | 21 August |
| Testing feedback incorporated | 10 September |
| Copyedit and proofread of new docs | 17 September |
| Draft status of docs removed, docs officially launched | 28 September |
| Process for updating documentation created | 1 November |
| This case study created | 8 November |
| Case study submitted | 16 November |
In our proposal budget we had estimated that the technical writer would spend 10-15 hours per week working on our project. Sam kept records of time spent and averaged 11.5 hours per week.
Results
What was created, updated, or otherwise changed? Include links to published documentation if available. Were there any deliverables in the proposal that did not get created? List those as well.
Three major use cases were documented with full user how-to guides:
How to add a new ingredient to GloriousPickle
How to add a variant ingredient to GloriousPickle
How to update or correct an ingredient in GloriousPickle
These guides also included new pull request templates to make contributions easier.
In addition, during the project Sam created a small Pickle Glossary of terms they learned, which was also published on the GloriousPickle project site.
We added instructions for updating these user how-to guides to our project wiki.
We had included creating a cheat sheet for contributors new to GitHub to help them use our processes and tools, but once we looked at the resources available we were able to fork another project's cheat sheet instead.
Metrics
What metrics did you choose to measure the success of the project? Were you able to collect those metrics? Did the metrics correlate well or poorly with the outcomes you wanted for the project? Did your metrics change since your proposal?
In our proposal, we proposed two metrics:
- number of ingredient-related pull requests
- number of pull requests from new contributors
For the month of September (the first full month since the publishing of the draft documentation) we saw a 5% rise in ingredient-related pull requests (from 20 in August to 21 in September) and we saw three new contributors who made four total pull requests (vs two new contributors who made two pull requests in August). We plan to track these metrics monthly.
Beginning January 1, we will also track the number of contributors who have made more than three contributions overall, starting quarterly after the documentation is published.
Anecdotally, we believe this new documentation has made a difference in enabling new contributors to add to the GloriousPickle ingredient database—one new contributor mentioned in the comment of their PR that they had tried before but hadn't completed their update because they didn't understand the process.
Analysis
What went well? What was unexpected? What hurdles or setbacks did you face? Do you consider your project successful? Why or why not? (If it's too early to tell, explain when you expect to be able to judge the success of your project.)
We are very pleased with the outcome of our Season of Docs project and consider it a success. The new documentation is clear and helpful, and we have already seen some growth in the number of ingredient-related pull requests and in the number of pull requests from new contributors.
We were also happy that nearly the entire GloriousPickle community participated, through giving feedback on the original proposal and by testing the new docs in draft form.
We did face a few unexpected hurdles—we were grateful that the wildfires in Sam's state did not cause any more damage than an internet outage! Also, we were sorry to lose @VinegarViv from the project; we wish her and her family the best and hope to see her again soon.
One thing we did not realize until Sam began working on the documentation was how many pickle-related terms and acronyms would be unfamiliar to someone coming into to our project with no pickling background. However, Sam made a point of keeping a list of every unfamiliar term and defined them through their own research and by asking community members for explanations and references. This Pickle Glossary will be a huge help in welcoming more people into the pickling community in future.
Summary
In 2-4 paragraphs, summarize your project experience. Highlight what you learned, and what you would choose to do differently in the future. What advice would you give to other projects trying to solve a similar problem with documentation?
In a word, our experience was pickletastic! We achieved our documentation deliverables and our metrics seem to be in line with our goals.
A huge part of the success of this project was how lucky we were in working with our technical writer, Sam Scribe. [I did not write this—Sam] Although Sam had no background in pickling or experience with GitHub, as an experienced technical writer, they were comfortable diving into a new subject area, asking questions, and doing research. Sam quickly picked up not just our project tools (we use a kanban board to keep track of work) but also our pickle-jokes! We are very happy that Sam has caught the pickling bug and that we've 'bottled' them in our community.
We would advise other projects to:
- Keep your proposals small and manageable. (We originally wanted to include documentation for using our estimator with industrial batch pickling machinery in our proposal, and only left it out because one of our community members deeply involved in open-sourcing pickle machinery was going to be writing her PhD thesis during the program.) We ended up having more than enough work to keep Sam busy!
- Leverage your networks when looking for a technical writer. Ask everyone in your community for recommendations. Although we found Sam through the Season of Docs GitHub, we felt confident working with them because we'd talked to several people during the application period.
- Welcome your technical writer into your community! Sam let us know that the enthusiastic attitude of the GloriousPicklers made it easy to ask questions.
- Help your technical writer get open source skills. Sam had never used git before, but after going through a few tutorials they got up to speed quickly. At first Sam was worried about how much feedback they might get from the community and how to incorporate it, but our community's 'rough consensus' model ('consensus is achieved when all issues are addressed, but not necessarily accommodated') made Sam confident in addressing criticisms using their technical writing expertise.
Appendix
If you have other materials you'd like to link to (for example, if you created a contract for working with your technical writer that you'd like to share, or templates for your documentation project, or other open documentation resources, you can list and link them here). The Appendix is also a good place to list links to any documentation tools or resources you used, or a place to add thanks or acknowledgments that might not fit into the sections above.
Acknowledgments
Our team would like to acknowledge the following people and things:
- @Dillicious would like to thank her partner and also low-fi hip hop radio
- @KimChiCook would like to thank his 할머니 for teaching him how to pickle
- @Piccalily would like to thank the Chicago Manual of Style Online
- @GherKen would like to thank his three kids for eating all the pickles he can make
- @VinegarViv would like to thank the rest of the team for accommodating her stepping down
- @BBChips would like to thank the best non-pickle food available, Tunnock's Caramel Wafers
- @GloriousPicklePat would like to thank the PickleDocs SIG for taking on this project
- Sam Scribe would like to thank the entire GloriousPickle community, but especially the Picklers who sent them canning jars during the jar shortage of the summer of 2021, starting them on the road to many delicious pickles!