Please Note: All screenshots are from publicly available open source documentation and websites.
The Problem
Kubeflow lacked explicit instructions for updating their website’s API reference page. This meant contributors had no clear direction on how to update the changes they made in the backend repository for the API (For example, updating description fields in the swagger file) to reflect in the frontend repository for the project website.
The Proposal
A Google employee I had worked with on past open source contributions notified me that a document sprint would be coming up in the next several days. I felt creating instructions for updating the API reference page would be a good project for me to pursue during the sprint since I had past experience with updating the page and first-hand knowledge of the tools that would need to be used.
I identified a Google engineer I had worked with on previous updates as my SME for the procedure, and once I notified them and received their consent I logged an issue in GitHub to propose that I would update a readme file in the website’s repository with the appropriate instructions.
The Process
I began by identifying the dependencies a user would need to install to perform the update and examining their own web pages or repositories for existing documentation on installation. If the installation instructions were clear and direct, I provided a reference link for the user. If I found the instructions unclear or not present, I added additional steps for the user to perform in my documentation alongside the links.
Updating the API Reference page was a simple three-step process, provided you knew what to do. Since this was not specifically written down anywhere, I made sure to document it with explicit command-line examples for the tools, drawing on my own trial-and-error experience when trying to make these updates for the first time.
The Outcome
I submitted a pull request from my GitHub fork and responded quickly to any suggestions my reviewers made. No significant issues were flagged, and my update was incorporated into the main repository smoothly. The process remains documented today so that anyone who tried to update the API reference documentation in the future shouldn’t need to reinvent the wheel trying to figure out how to do it!