Skip to content
← Back to Insights
DEVELOPER JOURNEY MAP 2.0 · PART 2 OF 3IN COLLABORATION WITH DOCFRAME

Where Builders and Their AI Stall

The stretch from first search to first build, and why friction there is harder to see.

First published on Docframe.

Developer Journey Map 2.0 · Part 2 of 3

Discover

AI didn't name you

Evaluate + Learn

AI couldn't read you

Build

AI couldn't recover

In Part 1, Dana Fujikawa from the Relaris Group introduced the Developer Journey Map 2.0 and highlighted one of the biggest shifts in the industry: builders now bring AI with them at every stage. Let's take a look at the part where most of them stall, from the first search to the first time their code runs.

I've spent 16 years writing documentation at Microsoft, Amazon, Cisco, and CARIAD, and this is the part of the journey I care about most. It's where documentation earns a builder's trust or loses it, and AI has changed how that plays out. Dana covered how to get beta docs ready for agents in Preparing Beta Docs for Developer Agent Experience (DevAX), so I want to cover where I see builders and their AI hit friction, and how you can start finding those spots in your own docs.

Friction you can't see

My first technical writing job was fixing a help center. Over six months, I updated about 1,500 articles, and the same tickets kept coming in. That was frustrating, but at least the tickets told us something. They pointed straight at the places where people couldn't find what they needed, or didn't trust what they found. The pattern hasn't changed much since. Gartner found that only 14% of customer service issues are fully resolved through self-service, and the most common reason is that customers can't find content relevant to their issue.

That trail is disappearing. When builders get stuck today, they ask their AI assistant long before they file a ticket or post in a forum. When Mintlify looked at a month of requests to the docs sites it hosts in March 2026, nearly half came from AI coding agents instead of browsers. If the assistant can't find the answer in your docs, it fills the gap with whatever it can find, or it recommends someone else. None of that shows up in your support queue, so from your side, nothing looks wrong.

When I audit documentation now, one of the first things I do is ask a few AI assistants the questions a new user would ask, then compare their answers to what the docs actually say. The gap between the two is where builders are stalling, and most teams have never looked at it.

Three places builders stall

Discover: AI didn't name you

Here's a question worth pondering before anything else: when a builder asks an AI assistant for a tool like yours, does yours come up? Many builders now ask an assistant for a short list before they open a search engine, and if yours isn't on it, it doesn't get evaluated. Even in a regular search, the summary often is the answer: Pew Research found that people clicked a traditional result only 8% of the time when Google showed an AI summary. When it didn't, they clicked traditional results 15% of the time. What AI says about your solution comes from what the web says about it, and your docs are a big part of that story.

Under this paradigm, there are a couple of challenges that come up repeatedly. The first is naming. Your team calls the feature by its brand name, and builders describe it by what it does. If no page connects the two, the assistant can't either. Nielsen Norman Group described this in its usability heuristics: speak "the users' language," not the system's. The second is gating. When rate limits, pricing, or security answers live in a sales deck or behind "contact your account manager," the assistant doesn't wait for the sales call. It answers from a forum thread or a competitor's comparison page instead.

Evaluate and Learn: AI couldn't read you

Once builders decide to try your solution, their assistant usually reads your docs before they do. And it doesn't read them top down like the way a person does. It pulls the pieces that look like they match the question and treats them as the answer. Markdown versions of your pages, an llms.txt file, and skill files give an assistant a cleaner way to read you.

That's where the curse of knowledge gets expensive. The people closest to the product write pages which skip steps that feel obvious, use an internal term before defining it, or leave a YOUR_API_KEY placeholder without saying where the real value comes from. When someone hits that gap, they ping a coworker. An assistant guesses, and the code it writes looks right but isn't. In the 2025 Stack Overflow Developer Survey, 66% of developers said they spend more time fixing AI-generated code that's almost right. Then the builder blames your product, not your docs.

Stale pages make it worse. A page describing last year's workflow is still a candidate answer, and nothing on it tells the assistant it's out of date. To rectify this, I recommend adding a version or review date to every page, and redirecting pages for retired features instead of leaving them up. In GitBook's 2026 documentation quality research, they found that among its docs sites getting at least 1,000 AI assistant questions a month, 83% had at least one page flagged as possibly incorrect or outdated. The more your docs get used, the faster stale pages surface.

Build: AI couldn't recover

People still decide what to build, but AI is increasingly deciding how. In Anthropic's study of about 400,000 Claude Code sessions, people made about 70% of the planning decisions, while the AI made about 80% of the execution decisions. So when an initial run fails, the first consumer of your error message is probably an AI.

Builders have always pasted error text into a search box. Now they paste it into a chat, and the assistant goes looking for a page that matches the exact message. If your troubleshooting docs are organized by cause but never quote the error, there's nothing to match. If the error only says "Request failed," there's nothing to explain. Nielsen Norman Group's guidance for error messages is to describe the exact problem and "offer some potential remedies," and that matters even more when the first reader is an AI. Either way, the build stalls, and from the builder's side, your product looks broken.

A lot of this comes down to timing. On one recent launch, I got access to the product portal 17 days before release. By then the error messages, names, and defaults had already been decided, and I was working backward from a finished product like any new user would. The lesson here is that good tech writers are your first users. Bring them in while those decisions are still being made, and catch these gaps before an assistant ever finds them.

Two quick checks to analyze how agents see your solution

You don't need a full audit to check how agents see your solution. Try these two checks which will tell you a lot:

  1. Ask three AI assistants what tool to use for your use case. Are you on the list, and do they describe you correctly? Then ask each one a question your docs already answer and compare what comes back.
  2. Point an AI coding tool at your quickstart and let it work on its own. Does it reach Hello World without help? While you're at it, paste your three most common error messages into a chat and see whether the answers point back to your docs.

If either provides an unexpected result, that's where you should focus next.

If you need a deeper dive into this, mapping the full journey, stage by stage, is the work Docframe and Relaris do together with clients. We can help you optimize how agents see your solution and contribute to the overall Developer Agent Experience (DevAX).

What's next

In Part 3, we'll look at what happens once the code runs: why community is now the trust layer, and what marketing and DevRel teams need to change.

In the meantime, explore the interactive Developer + Agent Adoption Journey. If you'd like a second set of eyes on where your builders stall, let's talk.

Relaris Group is a full-service developer relations (DevRel), developer marketing, and GTM agency helping technology companies grow developer adoption in the agentic age.

Sources

Docframe is a technical documentation consultancy that helps SaaS and developer tools teams build docs that people, and the AI tools answering for them, can find and trust.