Contribute to documenting Redocly's open-source tools
We successfully completed our first ever Season of Docs in 2021. To find out what we achieved over the course of the program, read our case study.
Technical Writer hiring update
Redocly has now successfully completed hiring their technical writers for the Google Season of Docs 2021.
- Heather Cloward will be joining us on our Redoc project, helping create product documentation and updating the README for the project.
- Anton Zolotukhin brings his immense experience working on open source projects and previous participant on Google Season of Docs 2019 and 2020, to our OpenAPI CLI project.
We received a large number of quality applications and it is heartening to see so many individuals eager to contribute to open source projects.
Season of Docs 2021 organizations
Redocly's open-source project application has been accepted in the Google Season of Docs 2021 program.
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.
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.
About our project
Redoc currently does not have comprehensive documentation. All project information exists in the README file on the GitHub repository and a few other topics within the docs folder in the repository. The current README.md on the Redoc GitHub repository is outdated and needs to be updated with relevant examples, screenshots and other information.
The OpenAPI CLI documentation is currently publicly available for users. There are sections in the docs that need to be updated or refreshed with relevant information. Users currently find it difficult to find information quickly, and some of the new features are not completely documented.
Our project’s scope
The technical writers working as part of this project will:
- Create documentation for Redoc and provide more examples of options, vendor extensions and updated screenshots. This content will be published on Redocly's publicly accessible technical documentation site.
- Update README for Redoc with relevant examples, screenshots and other information.
- Update current documentation on OpenAPI CLI, available on Redocly's technical documentation site.
- 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 would consider the project successful if, after publication of the new documentation:
- There is a decrease in the number of issues and StackOverflow questions by 20%
- There is an increase in the number of contributions for creating or updating documentation
Project budget
| Budget item | Amount | Running total | Comments |
|---|---|---|---|
| Technical writer/s to update, test, and publish new documentation | $10,500 | $10,500 | |
| Volunteer stipends | $500 | $11,500 | 2 community volunteers x $500 each |
| Project swag | $200 | $11,700 | Design and print swag (t-shirts and stickers) |
| Design docs assets | $550 | $12,250 | Create project docs branding, logos, and templates |
| Total | $12,250 |
Additional information
Previous experience with technical writers or documentation
Redocly currently has two technical writers working on documentation for their premium products. 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 be beneficial to technical writers working with us in the Season of Docs.
Previous participation in Season of Docs, Google Summer of Code or others
While Redocly as an organization has not participated in Google Season of Docs or Summer of Code before, one of our technical writers has been a participant in the Google Season of Docs 2019 and successfully worked with an open-source project to create documentation for their project. Our other technical writer is actively involved in the KDE community both as a mentor and a contributor.
Project ideas for Redoc
Update README for Redoc
Problem
The current README.md on the Redoc GitHub repository is outdated and needs to be updated with relevant examples, screenshots and other information. We need a contributor who can quickly get familiar with Redoc and improve the README for other community members.
As part of this project, the technical writer will also review closed issues in the Redoc repository, and use this feedback to update the README file.
How would we measure success?
- Decrease in the number of first-timer issues raised
- 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 and Redoc
Nice to have: Familiarity with GitHub flow, JSON schema, Project management skills
Tools we use: Slack, GitHub PRs and issues
Volunteers
As part of the project, we have the following volunteers:
- @Roman, can help with answering questions about our product code
- @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 and publish product documentation
Problem
Redoc currently does not have comprehensive documentation. All project information exists in the README file on the GitHub repository and a few other topics within the docs folder in the repository. We need a technical writer to create documentation for 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.
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.
Project ideas for OpenAPI CLI
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.
Organize and consolidate information
Problem
Our OpenAPI CLI documentation is sprawling and outdated in some places. Users raise issues or ask questions via the GitHub repository if they cannot find the information they are looking for.
As part of this project, use your information architecture and documentation skills to organize and consolidate information where appropriate and suggest ways to make the documentation more streamlined and responsive to customer feedback.
How would we measure success?
- Better structure and navigation for our documentation
- 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 reorganizing large and mature documentation sets, working with developers to improve information architecture
Volunteers
As part of the project, we have the following volunteers:
@Swapnil, happy 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.
Test our documentation for OpenAPI-CLI
Problem
Our current documentation for OpenAPI CLI covers a lot of information for various use cases. As part of this project, we want someone to come and test our documentation end-to-end, and identify opportunities for improvement.
How would we measure success?
- Decrease in the number of issues raised by new contributors
What skills would a technical writer need to work on this project?
Must have: Familiarity with GitHub and OpenAPI CLI
Nice to have: Testing tools
Volunteers
Encourage community members to sign up to help with specific tasks, for example:
@Anatolii, can help with answering questions about our tests @Andriyy, 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.