Reimagining documentation in the AI age: A conversation with Vercel’s Lee Robinson
Vercel’s Lee Robinson explores how AI reshapes API references, tutorials, and search, and why human-crafted educational docs remain essential.
Lee Robinson leads developer experience at Vercel, where he oversees both documentation and educational content for Next.js and the Vercel platform. With a massive docs codebase spanning thousands of pages that has grown over many years, Lee recently led a major docs redesign focused on stripping away complexity and refocusing on what matters most: content that humans actually want to read.
We sat down to discuss how AI is changing both the creation and consumption of documentation, why educational content is more important than ever, and the surprising ways that AI actually reinforces traditional documentation best practices.
How do you see AI changing the way people interact with documentation?
The thing that is funny to me is AI just accentuates all of the existing best practices. Writing good content doesn’t really go anywhere. Actually, it’s even more important because you’re needing to write something that’s accessible to both humans and AIs. Thinking about the visual structure of the page and making sure you have ample code blocks, and sparse but intentional use of bold and italics and other text formatting — all of that stuff matters for humans, and it matters for AIs as well to help give them more tokens and context about what’s important on the page.
The best practice has always been to include lots of code snippets, because devs will skim towards there and you want to give them good examples. Well, that’s doubly important with AI, because the examples are like the lifeblood of actually giving anything useful. And writing really concise and articulate docs — that was important for humans. But when the context window matters and every token matters, the conciseness and the brevity of the docs also matters a lot.
I’m curious about this world with AI agents where people are programming but staying within their editor the whole time. Is there still space for people to actually go and read the docs?
The best practices seem to matter more than ever. Your API reference isn’t going anywhere. Your API reference is actually the thing that the humans probably don’t want to parse through — it’s actually just feeder for your code editor or your AI tool. It’s just like your TypeScript types and your JSDoc autocomplete in your editor. You just want basically super intelligent source code assistance where it knows, “Hey, here’s every single possible permutation of the API that you could use. Here’s every single option it can take.” That’s what I want the AI to help me with in my editor.
So the API reference as a type of docs format — I think that’s not really something that humans will read as much in the future unless you're bored and you want to just read every single possible API reference. Rather than digging through potentially many, many, many different APIs, it’s nice if you can just ask an LLM about a specific API and get a usage example of that API. So that one feels like it’s going to be more AI-dominated.
Now, tutorials and guides — broadly speaking, educational material — that’s the type of stuff that will be increasingly human-focused. As a human, I want to go and take the course. The AI isn’t really taking the course. Yes, you can train the models on that raw material, but there’s a reason you’re building that educational material in a way that has some kind of structure where you step through and incrementally learn things. You have quizzes, you have checkpoints. It’s designed for humans with all of the general education best practices for how you build a curriculum. That still exists, for sure.
And you recently did a major redesign of the Vercel docs. What drove that?
We were going through the Vercel docs — massive docs codebase, thousands of pages, grown over many, many years. Mostly an append-only situation. We don’t delete docs very often, you’re mostly just adding new things. We did a docs redesign about a month ago because we were in the situation where you blink and then all of a sudden things are really complex. We had a top nav with dropdowns, we had a side nav with dropdowns, and then we had estimated reading time and suggested articles. You look at the page and we were like, “Holy shit, where's the content?” It was just stuff everywhere.
So we really stripped it all back. Again, with this thinking in mind of who’s reading this — it’s humans, and they just want to read the content. In the process of doing that we were recalibrating our content with the different docs framework of how we’re writing, either API reference or tutorials or guides. And in doing that we realized there was a bunch of duplicated stuff that was half API reference but also kind of half tutorial. In this new world we’re going to, it was like, yeah, just cut all that. The API reference can be completely auto-generated from the source code and focus on the educational part.
That’s interesting — so you’re moving toward auto-generating API references. How does that work in practice?
What we’ve done for our API docs, like our Vercel API docs, is that they are auto-generated from our OpenAPI spec, and then we build a documentation site based on that. For Next.js we haven’t yet done it, but I would like to move in that direction where it is generated from the source code.
The funny thing here is — and the reason why I was against this for a very long time — it’s six of one, half a dozen the other. You generate your docs from your source code, okay, now you’re writing your docs in your source code. It’s not like it’s gone, it’s just in a different location. But the advantage of writing those docs alongside the source code is that, generally, at least from what I’ve seen, one, you get better in-editor feedback because you can hover over something and then it shows the JSDoc popup. But two, some of the LLMs can read content from node modules where your docs have been included in the source code, which is just a little bit easier than having to go set up a bunch of extra things.
And talking of LLMs, how is AI impacting the creation of educational content?
AI is helpful, especially the most advanced models are helpful for shitty first drafts. It’s close-ish. It helps you maybe ideate on how you might structure the outline. Where I’ve seen it struggle is where I, as the creator, come up with an outline for the course, and then naively I’m like, “Okay, AI model, here’s the outline, write the course”. And then you do it and it’s missing so much detail. It’s very strictly trying to follow the outline. Sometimes I would even say, “You don’t have to follow the outline exactly, this is just inspiration”. And then it spits out exact headings based on the outline. I’m like, “Okay, well, that didn’t really work how I wanted it to”.
What I had hoped was I had given it this rough outline and it would go off and actually teach the material in a way that I would be interested in reading. But the problem is it can only know what you give it. So if I don’t give it the detail of what I want the educational content to be like, it’s not going to figure that out on its own.
So humans are still critical for creating that educational content?
Yeah, exactly. I think the content needs to be human-created, human-verified, and it needs to have that human touch. Educational content is about more than just conveying information — it’s about the way you structure the learning journey, the examples you choose, the way you anticipate where people will get confused.
We have a team separate from docs that is working on all things educational content. They have to very well integrate and be closely related to the documentation, but it’s not the same thing as the API reference itself.
To summarize — we still need people to write the docs, but people aren’t necessarily reading them in their raw format anymore?
Yeah, I think when you’re just trying to code quickly, people can stay in their editor and use the API reference through their AI assistant. But when you’re new to something and you don't know where to get started, the educational content feels like the best on-ramp into the docs experience.
It kind of depends on what you describe as docs, because for some people docs are the API reference and that’s pretty much it. For some other people, docs also include the educational content. For us, we think about them as separate but related.
This interview was published on 10 July 2025, and conducted as part of research for the 2025 State of Docs report.