Project Overview
Our goal for this project was to ultimately provide a better experience for a developer new to integrating with cPanel & WHM. We also wanted to provide a way for our developers to be more involved in our API documentation.
Completed January 2021
Tasks
Information Architecture, Content Strategy, UX Design, UX Writing, User Feedback and Testing, Project Management, API documentation
Team
Documentation Manager (me), UI Developers, Backend (Perl) Developers, Development Managers, System Administrators, Product Owner, Scrum Master, QA Analysts
Before
Challenges
Large ‘Wall of Text’
No clear direction for the user
Struggled to keep APIs accurate due to separation of code and documentation
Doesn’t follow the brand at all and has no strategy
After
The Solution
Streamlined design, following our brand guidelines
Better organization of content
Clearly defined paths for the user
Documentation is updated with the code
This project was a major undertaking and took the collaboration of a full feature team, the documentation team, and other developers, managers, and QA analysts to bring it to completion. From research and design to publication, it took a year and a half.
Project Details
Phase 1 – Research and Design
We had major challenges to overcome with this project. In the ‘Challenges’ above, I mention that no content strategy existed. A lot of the APIs themselves had no strategy or standard since until 2018 there were no enforced standards in how the APIs were written. This quickly became a monumental effort to convert and standardize over 1500 functions and we enlisted the help of every single member of product development.
A Product Owner and I collaborated on researching what products we would use to standardize and publish our developer documentation and settled on OpenAPI standards. Also, I really liked Stripe’s (https://stripe.com/docs/api) API documentation and after digging, met one of their writers and learned more about their process, which included OpenAPI standards.
We also determined the best way to ensure that APIs are properly designed and documented, would be to include them alongside the product code. This decision led us to utilize Redoc.ly as our publishing tool.
Phase 2 – Conversion and Implementation
This became an ‘all hand’s on deck’ phase, as we converted all of our APIs to an OpenAPI standard. Initially, our lead developers designed a scraper tool that gave us basic standardized docs for most of the APIs. A handful of APIs had to be manually converted due to their complexity, but mostly the APIs were verified and merged to our new repository.
At the beginning of this phase, I heavily collaborated with senior Technical Writers to create an OpenAPI Style Guide. We wanted to provide as much guidance for the developers and other team members who were assisting in the conversion process.
We also created a guide to explain how the APIs should be grouped and how the summaries for the subgroups should be written.
Phase 3 – Beta Launch
We launched the beta release and used the next couple of months to receive feedback and make changes and solidify the new procedures and publishing processes
We sent a survey to our support and customer service departments to get feedback on the site during this time as well.
Phase 4 – API Reference Completed – Build Developer Docs
Our last part of this project was to publish the API and Developer Guides. This phase was completed by myself and our documentation team. Below is a snippet of the project proposal for this phase. Happy to say we completed the transfer earlier than the anticipated date.
The completed product
Easy to navigate, clean lines, well-defined information, and on-brand design.