Please Note: All screenshots are from publicly available open source documentation and websites.
The Problem
Kubeflow’s Pipelines API reference page lacked any descriptions for their endpoints, making it hard to tell what some endpoints did.
The Proposal
As a previous open source contributor to the Kubeflow docs, I noticed this issue when I was looking for API documentation I could update and reached out to the Google team to see if I could get in contact with someone as an SME. After some deliberations over email we were able to get a volunteer from the engineering team who had background in the reference documentation and could answer any questions if necessary.
The Process
I knew relatively little about the Pipelines API starting out, so before I tried to document it I felt I should spend some time using and experimenting with the API endpoints so that I could gain a basic understanding of what theys do. I explained this to my engineering SME, who was able to provide some helpful tutorial links that I followed to create my own instances of Kubeflow Pipelines on both Google Cloud Platform and my local machine. From there I used the Postman app to test the API endpoints and examine the JSON.
Although this sounds simple now, I encountered numerous trial and error issues during my attempts to get a Pipelines instance set up and appropriately configured so that I could make successful API calls. In general, my strategy for resolving troubleshooting issues was to re-examine the documentation, search the issues tab on the GitHub Repo for similar problems, and query the Slack channel for resolution before I pinged my SME. When I did reach out to them, I clearly documented the steps I had taken and where I had looked for information to help direct their response.
The Outcome
After I was confident I had spent enough time exploring the API functions, I began to document the descriptions directly in the code files.
The team had set up a partially automated process that created a swagger file from the code comments, but getting the swagger file converted to a web page had to be done manually and required a separate pull request to a different repository for the Kubeflow website. Since there was no process-specific documentation on this I reached out to my engineering SME, who provided several tools they used to convert swagger to single file HTML.
Not all the tools were fully documented, and I went through several more problem-solving phases before I was able to successfully generate the web page. I would later leverage this experience in a separate project to document the process of updating API Reference portion of the website.
Once all PRs were submitted and approved, the Kubeflow website was finally updated with API endpoint descriptions!
