Work on Redocly's open-source docs

About Redocly

Redocly was founded in 2017 with the mission to get more consumers using APIs with less hands-on support. We were born out of Redoc, the popular open-source OpenAPI documentation software project used by thousands of companies worldwide. We make API design and documentation software with the goal to improve the developer experience. Our suite of products makes our customers’ APIs more accessible and resultantly, more loved by their end users and consumers.

Our open-source tools

Our open-source tools allow developer teams to create clean, accessible documentation to complement their APIs. By making sure that the project documentation is complete, accurate and up-to-date, community contributors can add immense value to their open-source projects. We currently have 2 open-source projects we maintain.

Redocly CLI

Source: GitHub repository

Documentation: Redocly website

An open-source CLI tool that helps users with quality control and publishing of their OpenAPI definitions. It can validate OpenAPI definitions according to built-in and custom, user-created validation rules; split a single OpenAPI definition into multiple files, or do the opposite (bundle a multi-file definition into a single file). It can also build a preview of reference docs - either with our open-source product Redoc or with its full-featured premium version.

Redoc

Source: GitHub repository

An open-source API documentation generator that takes an OpenAPI definition and creates three-pane-style HTML documentation from it. The look and feel of the generated documentation can be customized with configuration options and specification extensions supported by Redoc. The documentation can be generated as a single, fully portable, zero-dependency HTML file. One of the main advantages of Redoc is its extensive support for OpenAPI 3.0 specification features, and the ability to render specification components that many other similar tools do not support.

JSON to JSON schema

Source: GitHub repository

An open-source tool you can use to convert JSON examples to JSON schema.

About our project

Project achievements 2021

As part of Season of Docs 2021, external technical writers:

• Built Redoc documentation around installation, quickstart and deployment guides. We would like to expand on this and add more relevant documentation and use case examples.

• Updated the OpenAPI CLI documentation with relevant information, including the overview page, installation guide, and the OpenAPI CLI commands documentation.

Project scope for 2022

In 2022, building on the work the technical writers did in 2021, we invite technical writers to:

• Create documentation for Redoc including a troubleshooting guide and provide more examples of options, vendor extensions and updated screenshots. This content will be published on Redocly's publicly accessible technical documentation site.
• Create guides on how to use Redoc with other documentation site generators and tools.
• Update current documentation on OpenAPI CLI, available on Redocly's technical documentation site.
• Create quickstart guide and README information for our JSON examples to JSON schema tool.
• Organize and consolidate information and suggest ways to make the documentation more streamlined and responsive to customer feedback.
• Incorporate feedback from documentation testers (volunteers in the project) and the wider community.
• Work with the Redocly team to test existing documentation end-to-end, and identify opportunities for improvement.

Measuring our project’s success

Our contributors currently use GitHub issues, Write the Docs Slack channel, StackOverflow and other social channels to raise issues and fixes with the documentation.

We track all our documentation with HotJar and Google Analytics. Since July 2021, when we released product documentation for Redoc and started updating documentation for OpenAPI CLI project as part of the Season of Docs, we noticed:

• A 95% increase in the number of users viewing the OpenAPI CLI docs from July. We made a few changes to the information architecture of the documentation site, and that also helped users find content more easily.
• Quicker uptake of the Redoc documentation with the newly added content making an immediate impact for our open source project users. This was evident from the decrease in the number of support questions for this project.

For 2022, we would consider the project successful if, after publication of the new documentation:

• Increase product usage as measured by npm download statistics of 10% or more.
• Increase positive sentiment scores on the docs on specific pages.
• There is an increase in the number of contributions for creating or updating documentation.

Project budget

Additional information

Previous experience with technical writers or documentation

Redocly currently has two full-time technical writers working on documentation for their premium products and a part time technical writer working on our open source documentation.

The technical writers are responsible for scoping, planning and working with the development team to create documentation for new features and support material across Redocly's products.

We create content in Markdown, and use the GitHub flow to review content via PRs before publishing this content to Redocly's technical documentation site. We have a well-documented process of identifying, prioritizing and creating content that will benefit technical writers working with us in the Season of Docs.

Previous participation in Season of Docs, Google Summer of Code or others

Redocly participated, and successfully completed their project in the Google Season of Docs 2021. To find out what we achieved over the course of the program, read our case study.

Our in-house technical writers enjoyed mentoring our Google Season of Docs 2021 participants. They are also actively involved in global documentation communities, both as mentors and contributors.

Project ideas