Optimizing navigation and information hierarchy in Pulumi documentation


In this project, I transform Pulumi’s product documentation. The project aimed to increase content discoverability in a unified documentation experience. I took a strategic approach to breaking down the design vision into discrete parts, allowing our small team to flexibly implement changes and gauge impact.

The Pulumi Service dashboard UI, January 2023


User feedback highlighted unclear content architecture and inadequate cross-linking in Pulumi's documentation. Users not only struggled to find the information they were looking for, but were often unaware of the extent of the content offering. We wanted to improve discoverability while catering to users with varying levels of product familiarity.


I unified far flung documentation into a singular experience with tabbed navigation organized by doc type. The navigation allows users to easily transition between content and makes the scope of content offering visible from every page. I standardized layouts between doc types with attention to readability and a11y and laid the foundation to scalably introduce new content types.


We observed an 115% increase in page views to the Pulumi Registry—home to one type of documentation—after introducing the new navigation, indicating we successfully raised its visibility. Additionally, the page layout standardizations reduced instances of multiple H1 tags per page from 4628 to 70, a significant improvement for SEO and site accessibility. See more in the launch blog.

[The new experience] is much better for a nerd like me that is typically trying to get to API reference documentation, not the overview stuff.
User feedback, Summer 2023

A graphic representing Design Council's Double Diamond Method. Two adjacent diamonds each bisected with a a different stage of the design process: discover, define, develop, and deliver.


My design approach models Design Council's double diamond, emphasizing the divergent and convergent thinking of design. The artifacts featured in this case study are highlighted in the list below.


Current UX audit
Landscape analysis
Feedback collection
Internal interviews


Affinity mapping
Insights report
Stakeholder review


High fidelity prototypes
Design critique


Implementation support
Metrics tracking

Breaking down pain points into actionable insights

Affinity mapping feedback to visualize thematic groupings of user feedback.

Translating user needs into business value

Early wireframes proposing a navigation structure to unify existing documentation experiences in the Pulumi ecosystem.

An anatomical diagram of the proposed page layouts to facilitate discussion with stakeholders.

Refining the design vision with readability and accessibility in mind

Exploring an adjusted type ramp to compliment the new page hierarchy.

Design specifications for responsive break points.

Launching improvements to the documentation experience

A before and after comparison of the same documentation page after introducing new navigation and standardized page layouts.

Demo of the doc type navigation highlighting how the overall page layout persists between categories.

Page views to the Pulumi Registry over the course of a year- changes to navigation and layouts correspond to a jump in May 2023.

Up next

UX Bite: SaaS onboarding