Nobody Owns the Developer Experience

Ask a B2B SaaS company who owns their checkout flow and you’ll get a name. Ask who owns the developer experience and you’ll get a pause.

DevRel owns the docs, product teams own the endpoints, support owns the tickets. The experience a developer actually has, from first landing on the docs page to first successful call in production, cuts across all of them. Nobody’s job description covers the whole path.

Bad developer experiences rarely trace back to one team doing bad work. Every group in that list is competent and shipping. The failures collect in the seams between them, and the seams are the one place no team’s backlog reaches.

How API design work actually gets assigned

Murphy and colleagues interviewed 24 professionals involved in API design across seven major companies to understand how APIs get made in practice [1]. The pipeline they describe should sound familiar: new APIs are requested by upper management or solution architects, first specified by project managers, and then designed by engineers. One participant described the official version of this division of labor, and then punctured it:

“So there’s a theoretical view that says the offering managers or the product managers are the ones who are deciding what the functionality should be, and the API designers and the engineering team in general are just deciding how to convey that functionality how to present it. But in reality the two are much more closely constrained” [1].

The people doing this design work mostly learned it on the job. Only four of the 24 had learned anything about API design in school, and even at large companies, API design was a specialization held by a small group.

What about bringing in the people whose whole job is user experience? A few participants had tried. It mostly didn’t work:

“The big problem with bringing UX people in is that they don’t have a background in APIs or [even], in some cases, in programming. …They get overwhelmed by either the people or what it is that we’re putting in front of them” [1].

So the usability of the interface falls to the engineers, who never trained for it. Documentation fares no better. As one designer put it: “I do think developers and API designers treat documentation as an afterthought” [1].

And after release, the feedback loop is nobody’s job either. Designers of public APIs had little direct access to their users. Six of the designers in the study had actively monitored Stack Overflow and similar communities and failed to pull useful insight from them, because no tools exist to consume that community data in aggregate. Server metrics told them which endpoints got called, but only gave vague clues about why, and surveys suffered from low response rates and self-selection [1].

Specification here, design there, docs somewhere else, feedback nowhere. That is the org chart most developer platforms are built on.

What the seams produce

Fragmented ownership has a signature. When teams lack real use-case data, Murphy et al. found, they design around whatever is most straightforward to implement. So the API ends up mirroring its own internals rather than how customers want to use it. Meanwhile effort goes to the wrong places: “We often spend lots of time worrying about these edge cases that in essence zero or nearly zero people end up using” [1]. And for public APIs, every one of those decisions calcifies, because “if you change anything you basically break people”.

Zoom out from one API to a whole company and you get Google’s situation in the early 2010s. By their own account, the number of APIs across Google’s business units grew so fast that the result was “a user experience containing wild inconsistencies and usability problems,” where “users suffered a death from a thousand papercuts” [2]. Their example: three APIs all exposed the concept of a region, one as a full URL, one as a short name, one as a region code [2].

Sound familiar?

Each of those teams presumably made a defensible local decision. The incoherence lives between the teams, where nobody was looking.

What an actual fix looked like

In 2012, Google started a program called Apiness to take ownership of API quality and consistency. The mechanism was a design review process. An API owner submits their API specification, sample code, and supporting material as a document. An experienced design reviewer, plus a shadow reviewer in training, comments directly on it, and the review iterates until both sides sign off. Reviewers evaluate naming, level of abstraction, error messages, the resource model, and consistency with existing Google APIs. After sign-off, the same reviewers are automatically assigned to any future changes to that API [2].

Notice what this is: a standing organizational function whose entire purpose is the thing nobody owned before. The program started with 2 people and grew to 18 full reviewers with 6 shadow reviewers in training. It reviewed 43 APIs in a single year.

It worked, at least by the measures they published. Of 43 teams that went through review, 39 responded to a survey. Roughly 75 percent were satisfied with the process, and 91 percent felt their API’s overall quality had improved. One respondent captured why: “The design review was a nice sanity check that our APIs are understandable to people who didn’t write them” [2].

Why it’s harder than it sounds

Google’s own reflection on the program is the useful part, because the problems they hit are the problems anyone who creates a DevEx owner will hit.

Consistency. Once multiple reviewers exist, the reviews contradict each other. One team reported “a particularly frustrating cycle of reviews around naming conventions where I received contradicting messages” [2]. Another watched the recommended pagination token type go from string to bytes and back to string during their review.

Time. The single most frequent theme in Google’s feedback was how long reviews took. A quality gate is also a queue, and product teams experience a queue as a blocker. This perception can be especially nefarious in cultures that pride themselves in shipping fast. Speed takes precedence over quality practices.

Expertise. Reviewers were experts in API design, but not in every product domain. “We had a hard time getting the review team to understand what we were trying to accomplish in our API”. Some teams felt forced into a shape that didn’t fit: “Since our API doesn’t fit the cookie cutter mold of a RESTful API we had to make some design concessions” [2].

Dependencies. Reviewing multiple in-flight APIs at once means a change requested in one can cascade into others still under review.

None of this argues against ownership. It argues that DevEX ownership is a real function with staffing, training, throughput, and consistency problems. And companies that treat it as a memo (“the platform team now owns DevEx”) very quickly get back to these systemic problems.

If you’re smaller than Google

Most companies can’t staff an 18-person API review team, and I don’t think they need to. Two things from these studies transfer down.

First, put a name on the end-to-end experience. Murphy et al. found that when a company did not enforce its API guidelines through code review culture or linter tools, adherence was difficult. One designer at an acquired company said discovering the acquirer’s REST standard was a relief: “It was very hard [before that] to get our service engineers to consistently represent certain concepts exactly the same way” [1].

Second, put the review before the release, because that’s when decisions are still cheap. Public API decisions become permanent the moment customers build on them [1]. A two-person review habit at spec time costs almost nothing compared to a breaking change later.

The developer experience at your company is already being designed. It’s being designed by a project manager writing a spec, an engineer picking the easy implementation, and a writer documenting whatever shipped. The only open question is whether anyone ever looks at the whole thing.

References