A portal that developers couldn't navigate
PayPal's Developer Portal is the front door for millions of developers building payment integrations. It's where they come to understand the API, find documentation, test their implementations, and troubleshoot failures. In 2017, that experience was fragmented — inconsistent navigation, documentation buried in the wrong places, and an onboarding flow that left developers searching for answers before they'd written a single line of code.
As the embedded research partner for PayPal's online payments platform, I led a comprehensive mixed-methods study to understand where the portal was failing developers — and to give the design team the evidence they needed to make a strong case for a full redesign.
"Developer portals are products. If developers can't get started in minutes, they don't get started at all."
Understanding how developers actually use the portal
The risk with portal research is optimizing for the wrong moment. Teams often focus on individual documentation pages — improving clarity, reducing jargon, adding examples. But the real problem isn't any single page: it's the mental model mismatch between how PayPal organized information and how developers think about building a payment integration.
I designed the study to capture both the task-level friction (where does someone get stuck on a specific page?) and the journey-level friction (why are they on this page at all — and is that the right path?). That meant combining field research with structured in-lab testing.
Research design: two complementary methods
Field Research
Contextual observation sessions with developers in their own environments — watching how they approached integration tasks with the portal open, without task scripts or artificial constraints.
In-lab Usability Testing
Structured task-based sessions covering the core portal flows: onboarding, documentation navigation, API reference, and sandbox testing — with time-on-task measurement and post-task SEQ scores.
Stakeholder Synthesis
Workshops with 10 product teams to translate findings into prioritized recommendations — ensuring research output became roadmap input, not a report that got filed and forgotten.
Participant strategy
I recruited across three developer profiles that mapped to the primary use cases for the portal: developers new to PayPal integrations (highest onboarding friction), developers returning to expand an existing integration (navigation and discovery friction), and developers troubleshooting a live production issue (documentation and support friction).
This three-segment approach ensured findings weren't dominated by new-user experience alone — a common pitfall in developer portal research that leads to redesigns that improve first-run experience while making the everyday experience worse.
What the research revealed
The field sessions surfaced the mental model mismatch clearly: developers thought in terms of what they were trying to build (a checkout flow, a subscription integration, a webhook handler), but the portal was organized around PayPal's product taxonomy (Payments, Invoicing, Subscriptions, Payouts). These weren't the same categories, and the gap between them was where most developers got lost.
Navigation by use case vs. product name
Developers searched for "how do I add a checkout button" — not "Payments API." Reorganizing navigation around integration goals dramatically reduced time to first successful API call.
Documentation depth mismatch
Experienced developers were slowed by introductory content embedded in reference pages. New developers were dropped into reference docs before they understood the integration model. Neither group was getting what they needed.
Sandbox environment confusion
Developers frequently lost track of whether they were operating in sandbox or production. Missing visual cues and inconsistent state feedback was creating errors and eroding trust in the platform.
Error message failure
Error messages in the sandbox were API codes — not human-readable explanations. Developers were spending significant time cross-referencing error codes when clear error messaging would have resolved issues in seconds.
"I know what I want to build, but I don't know what PayPal calls it. So I'm just searching and hoping something matches."
— Participant, mid-level developer at a fintech startup
Building a research-enabled product organization
The Developer Portal redesign was the primary research output — but the more durable impact was on how PayPal's product organization used research at all.
Serving 10 product teams and 12 designers as a single embedded research partner meant I couldn't run every study myself. The choice was between being a bottleneck or building capacity. I chose the latter.
What research enablement looked like in practice
I ran a structured research mentorship program across the design and product org — working directly with UX designers, content designers, and PMs to build their ability to plan and run their own research, interpret findings, and distinguish between findings that warranted escalation and findings they could act on directly.
This wasn't just "how to run a usability test." It was teaching people to ask better questions — starting with the decision the research needed to inform, not the research method they thought they needed. That shift in framing changed the quality of the studies the team ran independently.
By the time I left PayPal, teams were regularly running their own discovery interviews and usability sessions — and bringing me in for synthesis and strategic framing rather than execution. Research had moved from a service function to a shared capability.
What I learned
Mental model mapping is underrated
The biggest problem in the Developer Portal wasn't any specific UI — it was the vocabulary mismatch between how PayPal named things and how developers thought about their work. Research that surfaces mental models is more valuable than research that just tests task completion.
Two-method studies earn more trust
Pairing field research (observational, naturalistic) with usability testing (controlled, measurable) gave the design team both the "why" and the "how bad" — the combination made the redesign recommendation much harder to push back on than either method alone.
Enablement scales; individual studies don't
The best thing a single embedded researcher can do in a large org is build other people's ability to do research. The studies I enabled others to run outlasted my direct involvement — and that multiplier effect is what makes research infrastructure valuable.
Research partnerships require mutual investment
Being embedded across 10 product teams meant building genuine working relationships with PMs and designers — not just delivering decks. The teams that got the most from research were the ones that brought me in early, not as a validator at the end.