Google Season of Docs 2021 - Results

Written by Antonio • Nov 18

Hi everyone.

In this article, I would like to share the results of my third consecutive year in Season of Docs. This time I was lucky enough to join the Redocly team to work on the OpenAPI-CLI project.

Completed Work

  1. Updated OpenAPI-CLI Overview page

    This update brought readers a more clear and concise overview of the OpenAPI-CLI tool and its main features.

    • Revised the page to be more consistent and organized following the DRY principle (DRY: Do not repeat yourself)
    • Updated structure of the document to be better oriented for the first-time readers
    • Removed information about installation as redundant (this information was added to the full-fledged quick start guide)

    Links to PR: PR#334

    Public links: Redocly OpenAPI CLI

  2. Created installation guide

    This update brought a fully-revised page that outlines all the possible installation variants to make it easier for a complete newcomer to start working with the OpenAPI-CLI as quickly as possible. The guide now combines installation methods depending on their type (local or global) listing the recommended ones at the top of the page.

    Links to PR: PR#337

    Public links: Installing OpenAPI CLI

  3. Created quick start guide

    This update brought a brand new page that guides a newcomer through a set of basic workflow, showing common use cases and usage of commands.

    Links to PR: PR#342

    Public links: Redocly OpenAPI CLI quickstart guide

  4. Organized and unified OpenAPI CLI commands documentation

    This update brought a fully-revised section related to OpenAPI CLI commands.

    • Revised all the pages to be more consistent and organized following the DRY principle (DRY: Do not repeat yourself)
    • Updated structure of the pages to provide more information about usage and available parameters
    • Tested all the commands to reveal undocumented parameters, features, and use cases

    Links to PR: PR#345, PR#350, PR#351, PR#353, PR#360, PR#361, PR#383, PR#384

    Public links: Redocly OpenAPI CLI commands, bundle, join, lint, login, logout, preview-docs, push, split, stats

    In addition, I submitted 3 issues to fix incorrect behavior of commands when passing certain parameters: #370, #371, #372.

Not Completed Work

  1. OpenAPI CLI guides

    Reason: big scope of work according to the proposal. Due to the huge number of activities described in the proposal, during one of the Fortnightly catch-up meetings, it was decided to de-prioritize updates to OpenAPI CLI guides and focus on ongoing activities instead.

  2. OpenAPI CLI Resources

    Reason: due to the huge number of activities described in the proposal, during one of the Fortnightly catch-up meetings, it was decided to consider updating the Resources section as an “out-of-scope” stage and take a closer look after the Google Season of Docs program.

Challenges, Achievements


  1. Outdated and irrelevant documentation.

    The problems are mainly related to the following:

    1. The documentation is open and everyone can contribute to it.
    2. High load of in-house technical writers (and other dedicated persons) that leaves documentation tasks of low impact without proper attention.
  2. Overlapping documentation. Some documents were created in different parts of the website and had overlapping sections. For example, installation and configuration. There were also documents with redirects. All these aspects made documentation harder to read, understand, and find.

  3. No local environment for documentation. There was no way to deploy a local version of the documentation which complicated documentation development. The existing solution using the Development portal required additional configuration, copy-pasting between source and portal repositories, and it was not flexible enough to deal with minor documentation changes.

  4. Time zones. Redocly team members work from different locations across the globe which resulted in limited time slots for active communication and review processes. In some cases, this lack of time was making the documentation development process a bit nervous.


  1. Creation of Quick Start Guide

    It is one of the most valuable achievements during this season. Not only this single document brought order to chaos in terms of incomes and outcomes but also allowed to walk the reader through the basic usage of OpenAPI CLI and its main capabilities.

  2. Unification of OpenAPI CLI commands pages

    All the commands pages were unified based on a single structure. With this update, users can get familiar with all the usage options faster, check examples, and common use cases.

  3. A new hire for a Technical Writer

    At the end of the program, the Redocly team posted a new job opportunity for a Technical Writer confirming the importance of documentation and all the improvements made into it during the Season of Docs.

Experience evaluations, Lessons

Experience evaluations


  1. Open-source organizations are in need of good documentation no less or even more than commercial organizations.
  2. Open-source organizations know well the price of poorly-written or non-existing documentation.
  3. Even the smallest contribution to the documentation of the open-source project is priceless and respected.
  4. Your karma is getting better when you contribute to open-source documentation.
  5. All the people who work in open-source organizations are great!
← Back to blog