My research reshaped Haven Cloud's developer documentation, and every article and code fix I recommended shipped.
I interviewed the sales engineers who used Haven Cloud's documentation to win and support customers, walked a real sales call through the docs screen by screen, and handed the docs team a redesign plan. The redesigned docs moved search into the top bar, kept a faceted menu in view, opened every article with an overview and a last updated date, and made every code sample wrap and copy cleanly.
Client
A global cloud provider
I changed names and details to respect my nondisclosure agreements.
My role
Product researcher, developer documentation
Focus
Interviews, a scored walkthrough, and a docs survey
Result
All 12 article and code fixes I recommended shipped
The people selling the cloud got lost in its documentation while customers watched.
Haven Cloud's documentation team was about to redesign its docs site, including the web address, search, the home page, and the navigation. The team asked another researcher and me to find out who used the docs, what those people needed, and why.
We studied the company's own technical sales engineers first, because they used the docs to bring in new customers and help them once they signed. A typical moment was a call with a customer who needed a few last answers before a deal closed. Search only worked when the engineer already knew the exact name of a feature, and customers asked about features by the names another cloud uses, so engineers had to translate on the fly. Articles read as a wall of text, the menus disappeared on scroll, and code samples scrolled sideways. Docs, blogs, white papers, and the console each looked different, so people could not tell which resources belonged together.
I started with the people who used the docs to win deals, then scored the docs against their real day.
I co-led the study with another researcher. Every step fed one shared redesign plan for the docs team. Click or tap a card to turn it over.
People wanted the docs to follow the way they search, read, and share.
The scores and the interviews told the same story. The docs reflected how the company was organized, while people looked for answers by the task in front of them. A customer does not care which team owns a feature. The customer cares about one cloud and one place to start looking.
I grouped the findings into three themes of consistency, error prevention, and information hierarchy, and I paired every finding with a suggested change, framed as advice for the team rather than a mandate.
- Search needed to show related terms and help people translate the names that other clouds use.
- Navigation had to stay in view, because people got lost once they went more than two levels deep.
- Every article needed an overview, the main steps, and a diagram before the detail.
- People needed to see when a page was last updated before they sent it to a customer.
- Code had to wrap, show syntax colors, and copy cleanly from every sample without a download.
- Pricing, related articles, and a way to reach the docs team belonged inside each article.
Click through a docs site built from the research findings.
I rebuilt the ideas from my research as a working prototype under the name Haven Cloud Docs, and AI wrote the code from my design. The articles, release notes, and prices are sample content. Turn on Research notes to see which finding each part of the page answers.
Things to try
- Select Research notes in the top bar, then open the numbered dots to read each finding.
- Search for vpc and watch search translate another cloud's term, then turn highlighting off.
- Open Connect a private network, switch the code to Python, and copy a sample.
- Copy the link beside a heading, then hide the menu to give the article the full width.
- Answer No at the bottom of the article and send a note to the docs team.
A night blue frame, one spruce accent, and dark code panels keep attention on the answer.
I pulled this style guide from the prototype. The palette stays quiet so code, diagrams, and steps carry the page, and every text color passes WCAG AA contrast.
Color
- Night
#121A2BThe top bar and the selected filter chip. - Spruce
#0F6B57Links, primary buttons, focus outlines, and service icons. - Spruce tint
#E5F1EDThe article overview and the current menu item. - Code night
#111827Code panels, with mint keywords and amber strings. - Signal rust
#B23F0AThe numbered research note dots. - Canvas
#F5F6F8The page background behind every white panel.
Type
Page titles
Connect a private network
Source Sans 3 Bold
Body
A private network keeps your servers off the public internet.
Source Sans 3
Code
hc network vcn create --display-name web-vcn
Source Code Pro
Components
Search in the top bar
Search sits on every page, maps terms from other clouds to Haven Cloud names, and filters results by docs, tutorials, release notes, and the blog.
Faceted left menu
Topics open and close with plus and minus, the current article lists its own sections, and the whole menu can hide to give the article more width.
Overview with a diagram
Every article opens with what the reader will do, the main steps as links, and a diagram of the finished setup.
Code panel
Samples wrap instead of scrolling sideways, switch between the command line and Python, and copy only the command, never the prompt.
Feedback footer
A yes or no question with optional reasons sends a note straight to the team that writes the article.
Principles
- Organize the docs around the reader's task, not the company's org chart.
- Show the big picture before the detail.
- Prove that a page is current before anyone has to ask.
- Make every sample work the moment someone pastes it.
12 of 12
article and code fixes I recommended that shipped in the redesigned docs
The redesigned docs followed the research, one recommendation at a time.
The docs team rebuilt the site in the company's design system. When I compared my before screens with the live docs, every change I had suggested for article pages and code samples was in place. Click or tap a card to turn it over.
I ran a year-long survey on the docs and used the answers to propose a benchmarking program.
Later, as a principal researcher, I ran a standing usability survey on the docs site for a year. The answers led me to recommend experienced software developers as the main readers, with writing that still works for an expert who is new to a feature. People asked for better search, more screenshots and diagrams, fixed broken links, current information, and a fast way to reach support. I proposed a competitive benchmarking program that would compare the docs with three major clouds on real tasks, using the System Usability Scale and the SUPR-Q.
There is plenty more where this came from.
Names, brands, and data in my case studies are changed to protect my clients.
Tell me about your project.
Tell me a little about it on my contact form, and a real person will get back to you soon.