How to meet developers where they are

When I was brand new to software development, I remember following an API tutorial that gave me a curl example.

“Ok, but what do I DO with this?” I wondered, staring at the screen. I was very green at that point; I didn’t realize I could add my API key and run it in the terminal. The tutorial didn’t explain that, and Google didn’t help much either because I didn’t know the right question to ask. I eventually figured it out, but not easily.

In the age of AI, that problem may seem quaint. Today, I could literally just ask ChatGPT “what do I do with this” and give it the code, or ask Claude Code to make the API call for me.

But the underlying problem hasn’t gone away. Whether you build docs, UIs, APIs, or anything else developers use, you still have to answer the same question: How do you meet developers where they are?

It’s not just documentation

Meeting people where they are isn’t a documentation-specific idea. Nor is it a developer-specific idea. It applies to just about every interaction you have with other people.

In my curl example, there was nothing wrong with the code. It was probably a perfectly good example of how to make the API call. I just didn’t know what to do with it. I didn’t need a different API, a different tutorial, or a whole beginner’s course on software development. I just needed someone to tell me where to run the command. One sentence would have done it.

Meeting people where they are means understanding the context they bring, and designing an experience that works for them.

Of course, this is easier said than done. We’re not mindreaders, and feedback isn’t always easy to get.

But after spending a lot of time thinking about this during a documentation information architecture (IA) revamp, I’ve landed on three things that matter most for developer docs: where they are in their journey, their knowledge, and their consumption. Together, these make up much of the context that developers bring.

1. Where they are in their knowledge

When you think about how much a developer knows, you might first think about their level of technical experience. Are they brand new to programming, or have they been writing code for 20 years?

But that’s only one part of it. Someone might be an incredibly experienced developer and know absolutely nothing about your products. Or they might be a relatively inexperienced developer who knows your APIs inside and out because they were trained on this one product for a specific job.

So this one is twofold: have you considered their experience as a developer, and their experience with your product terminology?

Imagine you’re a developer who wants to send an SMS notification from your application. You know what you want to build. But you don’t necessarily know which Twilio product you need, what it’s called, or where to find it.

On the flip side, imagine you’ve been using Twilio for 10 years. You know exactly which product you need, and you just want to get to its API reference. You probably don’t want to navigate through a bunch of newbie-oriented use cases to get there.

Both developers have perfectly reasonable expectations. And both should be able to find what they need.

2. Where they are in their journey

Now let’s say we’ve figured out what a developer knows. That’s great, but it still doesn’t tell us the whole story on what they need. Because the same developer can need completely different things depending on where they are on the development journey.

Think about someone who’s adding a new feature to an application. Depending on where they are in the development process, they might have five very different questions:

• Exploring: Can I do this?
• Planning: How should I do this?
• Building: Show me the code.
• Troubleshooting: Why isn’t this working?
• Maintaining: How do I monitor it and keep it updated?

We need content coverage for each of those questions, and we need to make the right info available at the right stage of the journey.

Beyond that, we need to anticipate what they don’t know they need. Someone exploring a new feature might not know they’ll need to make an architectural decision before they start building. But we know that, so we can help them discover that information at the right time.

3. Where they’re consuming the experience

When we design documentation, we spend a lot of time thinking about the experience on the docs site itself. The homepage, navigation, sidebar, breadcrumbs, and how everything connects. And we should! Those things are important.

But what if the developer never sees any of them?

Even before AI, developers frequently found documentation through Google. They’d search for something specific and land directly on a page, without ever seeing the homepage or navigating through the structure we’d built.

Now, they might ask ChatGPT a question and get an answer based on our documentation. Or they might ask Claude Code to implement a feature, and the agent goes off and finds the information it needs.

A page might make perfect sense when you’re viewing it on the docs site, surrounded by navigation that tells you which product you’re looking at and how it fits into everything else. But what happens when an AI agent retrieves that page independently?

Does it know which product the page is about? Which API version it applies to? Whether it’s current or legacy documentation? How it relates to other pages?

And, on an even more basic level: can it find your docs at all to begin with?

We still need to design a great navigation experience for humans. But we also need to make sure our content works when someone (or something) arrives at an individual page without any of that surrounding context.

We’re still trying to meet developers where they are. Sometimes, though, “where they are” is inside an AI coding tool instead of on our website.

Making all three work together

So how do you actually account for all of this in one documentation experience? That’s the question we had to answer with Twilio’s docs IA revamp.

We had more than 30 products, developers with wildly different levels of familiarity with Twilio, different stages of the development journey, and increasingly different ways of consuming documentation. And we needed one coherent system that worked for all of them.

To see how we did this at Twilio, check out the Programmable Voice docs, which feature guides by use case OR by product, landing pages sectioned by journey stage, and TL;DRs designed to help AI engines identify relevant content when developers ask questions in plain language.

But this will look different for every set of products, docs, and developers.

The best place to start? Do a quick survey and ask what’s missing. You may be surprised to find that developers tell you exactly what they need.