Due to strict confidentiality agreements, I can’t showcase the user interfaces for these projects. Instead, this case study pulls back the curtain on my practical process and a breakdown of what I did.
eye_tracking
Project overview
A developer platform doesn't fail all at once — it accumulates. After 50+ tools at Ocado Technology, good documentation stopped being a nice-to-have and became the difference between developers using the platform well or working around it.
MY RESPONSIBLITIES
content_paste_search
User research
account_tree
Information Architectureh
contextual_token
Interface Design
list_alt_check
Usability Tests
finance_mode
Data Analysis
PROBLEMS
Before we ran any research, the signals were already there:
Everything was consolidated into a single, managed documentation monorepo, reviewed and maintained by a technical committee. Instead of guessing which wiki, README, or Slack thread held the answer, developers had one consistent place to start.
We tracked usage from day one using FullStory — what developers searched for, what they read, what they ignored, and where they dropped off. This turned documentation from a one-off project into something the platform team could continuously monitor and improve.
Content was organised around jobs to be done, not platform structure. Guides were named after developer intent — "expose resources outside the account," not "use the API Gateway wrapper" — so developers could find the right tool even if they didn't know it existed yet.about.
To understand what good documentation looks like from a developer's perspective and what was concretely broken, we ran around 10 in-depth interviews with developers across different departments.
Developers used Ctrl+F to jump straight to what they needed on a page, rather than scrolling through it. This was the clue that long-form pages with in-page (right-hand) navigation would serve developers better than splitting content across many short pages.
Rather than imposing a user-facing taxonomy, we ran a card sorting session with three internal platform experts — the people with the deepest knowledge of how the platform was actually built. We gave them cards with tool names and asked them to group the tools and explain their reasoning. The categories came from the inside out, not from assumptions about how users might think.
Because we couldn't find one taxonomy that worked well for all our products and tools, we decided to invest in a really well-working search instead. Developers were already using Ctrl+F — they searched for phrases, not categories. A strong search experience meets every mental model where it is, without requiring users to learn a taxonomy first.
We adopted the Diataxis framework, separating all documentation into four distinct types: tutorials, how-to guides, reference, and explanation. Each serves a different user need, and keeping them separate solved the mixed-content problem the research had surfaced
Structured around jobs to be done. We named guides after developer intent, not implementation. Not "use the API Gateway wrapper" — but "expose resources outside the account." Jobs don't change even when the tools underneath them do.
The platform was built on MkDocs with the Material for MkDocs theme as the foundation — chosen because it gave us a solid, developer-familiar base to build on rather than starting from scratch.
I adapted the Material theme to the internal brand end-to-end: defining colour tokens, adjusting typography, and directing the front-end implementation. Mermaid diagram support was added for technical documentation. The Figma prototype built for validation was based on this adapted theme.
Search wasn't left to defaults. We customised Lunr.js to control how content was indexed, what appeared in search results, and what ranked at the top. The goal was a search experience that met developers where they were — surfacing the right content without requiring them to know the platform structure first.
Before rolling out platform-wide, we tested on a single piece of documentation first — the API Gateway wrapper — chosen because it was well understood and had real potential users we could recruit.
Built a scenario around a job to be done: expose a resource outside the account. Developers used the documentation to complete the task, thinking aloud as they went. The Diataxis structure held up — keeping content types separate was noticeably usable. A few content gaps surfaced and were fixed before rollout.
The platform launched initially without categorisation, focused on tools, products, services, and search. Categorisation was introduced as an ongoing process after launch.
We used FullStory to track behaviour before and after the redesign , establishing a baseline of how developers entered and moved through documentation, and monitoring for changes post-launch.
What developers were typing — tool names, job names, or something else entirely. Which searches returned no results, pointing to content gaps or indexing problems.
Most viewed documentation — what was actually being used. Zero view documentation — what was invisible or irrelevant, which became the basis for the next research cycle. Scroll depth — whether developers were reading or landing and leaving.
The best design decisions on this project didn't come from me — they came from domain experts who understood the platform deeply. My job was to create the conditions for that knowledge to surface.
