In 2019 the developer experience team worked on a complete overhaul of our API design and docs site. I was the primary UX designer, working closely with a content designer and engineering team. This effort included exploratory research, content design, UI design, and information architecture.
The Problem
At the time, HubSpot had close to 500 pages of documentation for developers building on its public API platform. While there was plenty of high quality content, users were having trouble finding what they needed. Poor usability and discoverability of API docs content ranked #2 on our "developer pain index" through NPS survey and qualitative feedback channels.
Coupled with a recent redesign of the API system itself, this meant the docs navigation and in-page content were both in need of an overhaul. The visual design and UI components reflected in the docs site also needed a refresh to align with HubSpot's more recent design system.
My Approach
Exploring new IA and site nav
I started this project with a content audit of the existing docs site and planned changes to the API architecture. I worked closely with engineering teams and a content designer to build out a proposed information architecture for the new docs site. We landed on a plan to split "guide" content from "endpoint" content for each API feature area, to help differentiate human-written overview content from generated lower level specs.
We began creating wireframes and sample docs page comps right away to help validate the IA direction. Through usability testing these mocks as well as running one or two leaner IA studies, we were able to land on a workable design to move forward with.
From wireframes to component and layout specs
I then began planning out the detailed designs, starting with understanding the types of page content we'd need to support. I drafted several page templates for content types - onboarding, guides, and endpoint docs. I built those pages out in mid-fidelity and spent time defining component specs for development as well.
New quality-of-life tooling
As part of this redesign we also created several new features to help developers learn and explore the API. One of these was a "Test call" feature provided for each documented endpoint.
This endpoint test feature would allow developers to run a mock API call directly from the docs site. It would use a provided API key to send a configurable sample payload, and then display the response. Developers could easily copy/paste the generated sample request or response to help understand the structure of the API and plug those things into their own code.
