2021 Case Study Report

Current phase:
The 2021 Season of Docs program finished on December 14, 2021. See timeline.

Note: This report summarizes data from the original program applications and from the organizations’ final case studies. The full case studies are linked from the 2021 Season of Docs results page.

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


  • 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

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.

A bar graph showing the number of projects using each OSS license: Apache 2.0: ten programs; 3-clause BSD: five programs; MIT: five programs; GPL 2.0: 4 programs; LGPL 2.1: 4 programs; Mozilla Public license 2.0: 3 programs; Artistic, Boost, and 2-clause BSD: one program each

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:

A bar graph showing the problems reported by organizations: Documentation is lacking for specific use cases of aspects of a project: 14 projects; Documentation is disorganized: 14 projects; Documentation is outdated: 6 projects; Documentation is not consistent: 3 projects; Documentation needs to be converted to a different tool, platform, or format: 2 projects

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.

A bar graph showing the documentation types created: Tutorials: 9 projects; How-tos: 6 projects; Getting Started: 3 projects; Examples: 3 projects; Reference: 3 projects; API Docs, Video, Quickstart, Templates, Landing page: 2 projects each

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.


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:

A bar graph showing documentation success metrics: Fewer project issues/questions: 13 projects;  More visitors to documentation/docs usage: 9 projects; More contributors/pull requests: 8 projects; More documentation pull requests/contributions: 7 projects; Total number of docs created: 5 projects; Increased documentation satisfaction (via survey), Increased project use, More direct feedback on documentation pages: four projects each; Better SEO: three projects; Total percentation of documentation converted and Total percentage of target info covered by docs: two projects each

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.

A bar graph showing the source of technical writer candidates: Applied directly to program: 7; SoD GitHub or previous SoD participant: 4; Write the Docs Slack or Community member: 3 each; Applied via jobs site (Upwork, LinkedIn) or Google Summer of Code or Code-In alumni: 2 each

(Note: not all projects indicated in their case studies where they recruited their technical writer candidates.)

Common issues in working with technical writers

A bar graph showing technical writer issues: TW dropping out: 8 projects; Communications issues: 6 projects; TW onboarding: 4 projects; TW recruitment; Hiring or payment; Project tooling setup: 3 projects each

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.

A bar graph showing the number responses to the followup survey: May survey: 13 responses; August survey: 21 responses; November survey: 12 responses

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:

  1. Are you still working with your Season of Docs technical writer?

A bar graph showing ongoing participation by technical writers, per survey: in May, 6 projects had technical writers either participating or answering questions; 1 project had no ongoing technical writer involvement. In August, 11 projects had ongoing technical writer participation; seven projects had no ongoing technical writer participation, and 3 projects had technical writers answering questions. In November, 5 projects reported ongoing technical writer involvement; 3 projects reported no ongoing technical writer involvement; and 4 projects reported technical writers answering questions.

  1. If your technical writer is still working with your project, are they being compensated in any way?

A bar graph showing the number of projects reporting their project compensation for technical writers in each survey. In May, 5 projects reported their technical writers were being paid for ongoing work; 4 projects reported their technical writer was unpaid. In August, 4 projects reported paying their technical writer and 7 projects reported their technical writer was unpaid. In November, two projects reported paying their technical writer, and 5 projects reported their technical writer was unpaid.

  1. At this point, do you feel your documentation project is successful?

A bar graph showing the number of projects reporting success against metrics in each survey. In May, 6 projects reported their metrics had been met; 6 projects said it was too soon to tell, and 2 projects had met adjusted metrics. In August, 16 projects reported that metrics had been met; 3 projects reported adjusted metrics had been met; and 2 projects reported it was too soon to tell. In November, 9 projects reported metrics had been met; 3 projects reported adjusted metrics had been met, and no projects reported that it was still too soon to tell.

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.