Current phase:
The 2021 Season of Docs program finished on December 14, 2021. See
timeline.
About Season of Docs
Season of Docs is a sustainability program managed by the Google Open Source Programs Office. The goals of Season of Docs are to:
- Provide support for open source projects to solve project problems with documentation
- Give technical writers opportunities to gain experience in open source
- Raise awareness of open source, documentation, and technical writing
- Collect and share information about effective metrics in open source documentation
More information about Season of Docs is available on the program’s website.
2021 program overview
2021 program changes
In 2019 and 2020, organizations and technical writers each applied to the Season of Docs program separately, and technical writers were matched with organizations by Season of Docs program administrators. Organizations provided mentors to work with the technical writers, who received a stipend for their work based on their location. The program measured whether the technical writers, mentors, and organization admins were satisfied with their participation in the program, but did not measure documentation outcomes.
In 2021, the Season of Docs team made significant changes to the program, shifting the focus towards measuring documentation outcomes and allowing more flexibility for the organizations and technical writers.
- Organizations applied with project proposals, including a budget and proposed metrics
- Technical writers no longer applied through Google to be matched with organizations, but applied directly to the accepted organizations
- Accepted organizations received grants via Open Collective, which they used to pay technical writers
- Compensation for the technical writers was set by the organizations
- Organizations submitted final evaluations and case studies and answered followup surveys
2021 general findings
Organizations
- The changes in the 2021 program led to fewer organizations applying (we saw 30% fewer organizations applying in 2021 vs. 2020) but the 2021 organization admins were slightly more satisfied with the program than the 2020 admins (93% v 91%)
Problems, doctypes, and metrics
- Most projects focused on creating documentation to reduce maintainer burden (through reducing issues/questions) and/or increase project participation (either by project users or contributors).
- 50% of the accepted organizations created Tutorial or How-To content.
- More than 50% of the accepted organizations considered their current documentation lacking, disorganized, or outdated.
- Projects generally wanted to measure their documentation effectiveness through interactions, especially fewer issues raised and more visitors to docs and participation in projects.
- As of November 2022, with 25 of 30 projects responding:
- 18 projects said they had met their original metrics
- 5 projects had met revised metrics
- 2 projects said it was still too soon to tell
Program participation
- Recruiting, hiring, and paying technical writers was the most difficult part of the program for organization administrators.
- As of November 2022, with 24 of 30 organizations responding:
- 18 organizations were still working with their Season of Docs technical writers (either as a continuing contributor or a resource to answer questions)
- 4 organizations were working with their Season of Docs technical writers in a paid role
- 18 organizations were still working with their Season of Docs technical writers (either as a continuing contributor or a resource to answer questions)
2021 highlights
- Multiple projects indicated that their technical writer intended to continue working with their project after the end of the Season of Docs program
- Metanorma had so many qualified technical writers apply that they found matching funds in order to hire an additional writer to work alongside the Season of Docs-supported writer during the program
- Moja Global found that the community was very engaged around documentation and set up a new Documentation Working Group to allow more contributors to participate in project documentation
2021 summary data
In 2021, 82 organizations applied and 30 open source organizations were accepted to the program. (See the Creating Your Application guide for the selection criteria.) The full list of participating organizations can be found on the Season of Docs website. All 30 accepted organizations submitted their final case study report to complete their participation in the 2021 program.
About the organizations
The organizations participating in Season of Docs 2021 represented a diverse range of open source projects. The 2021 cohort included:
- Large language projects such as Julia, Perl, and R
- Projects in education, climate, fintech, healthcare, library services, machine learning, mass spectrometry, public contracts, and robotics
- Developer-focused projects, including chaos engineering tools, fuzzers, chatbot SDKs, software composition analysis pipelines, performance monitoring tools, and visual programming tools
- Documentation projects for documentation tools, such as Redocly and Metanorma
Python ecosystem projects were the largest subcategory. The 2021 cohort included ArviZ, NumPy, MicroPython, PyMC3, PyTorch-Ignite, and SymPy.
We did not collect any metadata about the projects (such as date founded, geographic distribution of contributors, number of contributors, or size of user base).
We did ask projects to indicate which open source license they used.
The documentation problems outlined by the 2021 organizations are very common problems in both open source projects and in technical documentation in general.
The top problems that organizations were hoping to solve in the 2021 program included:
Note that organizations could report multiple documentation problems. For more specifics, see the Season of Docs 2021 results page, which links to full case studies for each organization.
Types of documentation created
Tutorials were the most commonly mentioned documentation type in the 2021 case studies.
Other documentation types mentioned in case studies included Docs-as-code pipeline, Diagram, Glossary, Style Guide, FAQs, Internationalization, Codelab, Content model, Modules, Concept documentation, Error messages, User research, Readme, Knowledgebase.
Some of these categories are fuzzy and a single documentation project could contain multiple documentation types or features.
Several projects specifically referenced using the Diátaxis framework as a guide for planning their documentation types.
For more specifics, see the Season of Docs 2021 results page, which links to full case studies for each organization.
Budgets
In 2021, the average budget request was $10,200 and the median was $10,000. Only three organizations requested and received the maximum possible grant ($15k) and another three requested the lowest possible grant ($5k).
The metrics
Projects outlined in their case studies the metrics they were using to gauge the success of their documentation projects.
The top proposed metrics were:
Other proposed metrics included GitHub stars, Time spent on page, Mailing list conversions, Qualitative user testing, Number of participants in forums, Number of partners/volunteers/integrations.
Because of the short window between finishing the technical writing projects and submitting the case studies, most of the 2021 cohort had not been able to collect enough data to determine whether or not their initial metrics had been met.
For more specifics, see the Season of Docs 2021 results page, which links to full case studies for each organization.
Working with technical writers
The biggest change to the Season of Docs program in 2021 involved how projects worked with technical writers. In earlier seasons, technical writers applied directly to Google and were matched by the program administrators with projects, and were paid a flat stipend directly from Google.
In 2021, technical writers applied to the projects directly and the projects set the budget for technical writer compensation, with payments made via the Season of Docs Open Collective fund.
Most of the projects participating in the 2021 program had little or no experience in recruiting or hiring technical writers, and many projects called out this part of the process as one that needs more support. In response to this feedback, the Season of Docs team added documentation for creating technical writer agreements to the program guide.
Hiring recommendations
Projects were asked to make recommendations for other projects interested in participating in Season of Docs. The top hiring recommendations were:
- Share the recruiting materials for technical writers as early as possible, even before you have been accepted to the program. Ask your community to refer possible candidates.
- Share widely outside the project channels. Use inclusive language and directly encourage candidates from underrepresented backgrounds to apply.
- Understand what tools are essential to your documentation creation process and recruit technical writers with experience using those tools.
- Create clear expectations for the technical writer about deliverables and milestones, communications channels and check-ins, and payment processes and timing.
- Consider investing in community members and helping them grow as technical writers by using the Season of Docs technical writer to provide mentorship and coaching.
- Budget more time than you expect for onboarding technical writers and answering questions and providing support during the program, especially if the technical writer does not have prior experience in your project’s domain.
- Document your recruiting, hiring, and onboarding process to use for future projects.
(Note: not all projects indicated in their case studies where they recruited their technical writer candidates.)
Common issues in working with technical writers
Technical writers in several projects had to drop out due to COVID or other illnesses, or because of family responsibilities related to the pandemic. Some projects reported communications issues involving timezone mismatches or internet connectivity problems.
Projects found that they underestimated the difficulties involved in onboarding into their communities or in setting up their project’s docs toolchain.
Some projects had delays in paying their technical writers because of banking issues with Open Collective or because the writers’ home countries had payment restrictions.
The program documentation around Open Collective fees was not clear: Google covered the Open Collective transaction fees for the initial transfer of funds to the projects, but not transaction fees imposed by some other payment channels (such as currency conversion fees). We'll work to make this clearer in the documentation for future programs.
Followup surveys
As part of the Season of Docs program, projects were asked to participate in followup surveys. Three surveys were sent in May, August, and November 2022.
The followup survey asked projects to confirm that their proposal and case study links were still active. The survey also included questions about the success of their projects (as determined by the metrics they set in their case study) and the continued participation and compensation of the project technical writers:
- Are you still working with your Season of Docs technical writer?
- If your technical writer is still working with your project, are they being compensated in any way?
- At this point, do you feel your documentation project is successful?
Future questions
As always, the more we learn about documentation in open source, the more we want to learn! In future seasons, we hope to learn:
- Whether project domains are correlated with doctype choice or metric choice
- Which technical writer hiring and onboarding practices are most effective for project completion and technical writer retention
- Reasonable timelines for measuring documentation effectiveness
Although there are many questions we'd like to investigate, we also want to respect the time of the open source project admins and maintainers who participate in Season of Docs. The top priority of the program is supporting projects in solving their problems with documentation.