Last updated

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

Budget itemAmountRunning totalComments
Technical writer to update, test, and publish new documentation$5000$50001 x Technical Writer
Volunteer stipends$500$5500Community volunteers
Project swag$200$5700Design and print swag (t-shirts and stickers)
Design docs assets$300$6000Create project docs branding, logos, and templates
Total$6000

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

Create short videos

Problem

Both our OpenAPI CLI and Redoc documentation is text-heavy and contains complex information, particularly around rules, commands, and decorators that can benefit from short videos.

As part of this project, use your video creation and editing skills to simplify the documentation and provide users with alternative ways to learn more about the products.

How would we measure success?

  • Increase in the number of users viewing the feature videos.
  • Decrease in the number of issues raised for topics covered in the documentation.

What skills would a technical writer need to work on this project?

Nice to have: Experience creating and editing videos.

Volunteers

As part of the project, we have the following volunteers:

@Ivana, to review video scripts @Swapnil, to review docs pull requests

Contact info

Technical writers interested in working on this project can email gsod@redoc.ly. Please include links to your technical writing work or portfolio/résumé/CV.

Create and publish product documentation for Redoc

Problem

Last year, we converted the Redoc README file on the GitHub repository into installation instructions. We need a technical writer to create documentation for various Redoc features and provide more examples of options, vendor extensions and updated screenshots.

How would we measure success?

  • Decrease in the number of issues raised for topics covered in the documentation
  • Increase in the number of new stars (More stars will validate the usefulness and effectiveness of the docs)

What skills would a technical writer need to work on this project?

Nice to have: Experience creating documentation sites, knowledge of GitHub flows, familiarity with Redoc.

Volunteers

As part of the project, we have the following volunteers:

@Ivana, to review docs pull requests @Swapnil, can assist with discussing information architecture of the documentation site

Contact info

Technical writers interested in working on this project can email gsod@redoc.ly. Please include links to your technical writing work or portfolio/résumé/CV.

Update current documentation for OpenAPI CLI

Problem

The OpenAPI CLI documentation is currently publicly available for users. There are sections in the docs that need to be updated or refreshed. These sections include, but are not limited to, custom plugins and rules. We need a technical writer (ideally with a developer background or experience in development) who can update the OpenAPI CLI documentation with these guides, as it involves building and testing custom plugins.

How would we measure success?

  • Decrease in the number of issues raised by new contributors
  • Increase in the number of new stars (More stars will validate the usefulness and effectiveness of the docs)

What skills would a technical writer need to work on this project?

Must have: Familiarity with OpenAPI

Nice to have: Familiarity with Github flow, JSON schema, Experience with validation/linting tools, Project management skills

Tools we use: Slack, GitHub PRs and issues

Volunteers

As part of the project, we have the following volunteers:

@Swapnil, happy to review docs pull requests @Ivana, can walk through current contribution process with technical writer

Contact info

Technical writers interested in working on this project can email gsod@redoc.ly. Please include links to your technical writing work or portfolio/résumé/CV.

Create documentation for our JSON converter tool

Problem

Redocly recently launched a new open source project for converting your JSON examples into valid JSON schema (JSON or YAML format).

We need a technical writer (ideally with a developer background or experience in development) who can help us create a README and a quickstart guide for this new converter tool.

How would we measure success?

  • Decrease in the number of issues raised by new contributors
  • Increase in the number of new stars (More stars will validate the usefulness and effectiveness of the docs)

What skills would a technical writer need to work on this project?

Must have: Familiarity with JSON schema, YAML and OpenAPI specification.

Nice to have: Familiarity with Github flow, Experience with converter tools

Tools we use: Slack, GitHub PRs and issues

Volunteers

As part of the project, we have the following volunteers:

@Ivana, happy to review docs pull requests and walk through current contribution process with the technical writer

Contact info

Technical writers interested in working on this project can email gsod@redoc.ly. Please include links to your technical writing work or portfolio/résumé/CV.

Bring your ideas!

About Redoc

Redoc is an open-source tool that generates API documentation from OpenAPI specifications. Using Redoc, you can create clean, customizable documentation with a three-panel design. Developers and contributors can write descriptions using Markdown.

Your project ideas

Outside of the project ideas listed above, we would love to hear your ideas on how you think you can improve our documentation and positively impact the developer experience. This could be in the form of tutorials, videos, training courses etc.

Feel free to contact us with your ideas.

Contact info

Technical writers interested in volunteering and proposing ideas can email gsod@redoc.ly.