Every new hire pulls a person off their own work for days. The quality of the onboarding depends on who happens to be free that week and how good they are at explaining things. Two people who join the same month get completely different starts. And whoever onboards them spends the same afternoon explaining the same process they covered last month.

I led a codelabs program at a large enterprise to fix exactly this. Here’s the thinking behind it.

One-to-one teaching doesn’t scale, and it isn’t consistent

The problem with pairing isn’t that it’s ineffective. It’s that it’s expensive and uneven.

The cost is obvious: senior time is the scarcest resource on any team, and onboarding spends a lot of it. The unevenness is the quieter problem. When the lesson lives in a person’s head, every delivery comes out a little different. One mentor remembers to explain a key step, another forgets. One walks through the whole process, another says “you’ll pick it up.” New hires end up with different mental models of the same system, and the gaps show up months later.

Codelabs move the lesson out of the mentor’s head and into something repeatable. The senior person’s knowledge gets captured once, and every new hire works through the same path. Mentors are still there for the hard questions, but they’re not re-teaching the basics every time someone joins.

Start with the use cases new hires actually hit

It’s tempting to document the whole system. We didn’t. We started by listing what a new hire actually has to do in their first weeks, the real tasks, not the org chart.

These were the core workflows they'd run no matter which team they landed on, the end-to-end processes that touch several systems at once. They're also the steps that cross team boundaries, which is exactly where reference docs leave gaps.

A handful of codelabs covering the most common first-month tasks does most of the work. We weren’t trying to teach the whole system. We were getting people through the paths they’d actually walk in their first weeks.

Build each one the same way

Every codelab in the program followed the same anatomy: a real scenario, one golden path, a starting point, checkpoints along the way, and a reference solution to compare against.

Consistency matters at scale. When a thousand people go through the same set of exercises, the structure has to be predictable, and the quality can't depend on who wrote which one. I wrote about what makes a good codelab in a previous post.

What changed

The first task stopped being a three-week ordeal. New hires went from an empty starting point to shipping something real on their own, without waiting to catch a senior person at a free moment.

Mentors got their time back. And because everyone worked through the same exercises, the team finally had a shared baseline. When someone said “I did the onboarding codelab,” everyone knew exactly what they’d learned.

Onboarding stopped being a tax on our best people. It became something the system could absorb at scale.

A codelab is a guided exercise to learn how to build something real. Not a tutorial that demonstrates one feature or a reference page covering all the available options. It takes a learner from an empty starting point to a working result, using the tools and conventions of the team they’re joining.

I made the case for why codelabs are the internal docs most teams are missing in an earlier post. This one is about how to build a good one. Here’s what makes them work.

Start with a scenario, not a feature

The strongest codelabs open with a real task. “Build a service that handles webhook events from our payment provider” pulls the learner through decisions, sequencing, and tool choices the way real work does. “Learn how to use the webhook library” doesn’t. It teaches a feature in isolation, and features taught in isolation never leave the codelab.

A quick test: if the title sounds like a generic heading it could live in your product docs to cover different use cases, the scenario is too narrow.

Pick one golden path

A codelab is not reference documentation. It shouldn’t explain every option and every alternative. Pick the one path that solves the main use case and walk the learner down it.

Real projects work this way too. You don’t implement your data layer in five databases so the team can choose later. You pick Postgres because of a specific reason and move on.

A codelab should make the same kind of decision. If there’s a meaningful alternative worth knowing about, mention it in a line and link out, but don’t fork the exercise to cover it. Every branch you add is another place to get lost.

Hand them a starter repository

Nobody should be setting up a project from scratch before they can begin. The starter repo carries the boilerplate, the dependencies, the config, and clear placeholders for the work ahead.

Setting up an environment is a different skill from learning a workflow, and mixing the two means the learner burns an hour debugging dependencies before they reach anything you wanted to teach.

Build in checkpoints

Every step needs a single goal and a way to confirm it worked. “Your service should now respond to a test webhook with a 200.” That way the learner knows they’re on track instead of discovering at the end that something broke back at step three.

Without checkpoints, a codelab becomes click-through-and-hope. People reach the end without being sure what they were meant to learn, which means they didn’t learn it.

Give them something to compare against

When they finish, the learner should be able to hold their work up against a reference implementation. Not just to check it runs, but to see what the senior-engineer version of the same task looks like to be able to compare. This is half the value of a codelab, and over time you build up a showcase of sample projects that follow your best practices.

Where good codelabs go wrong

The most common failure is drift: the underlying tools change, the codelab doesn’t, and now it teaches an API that no longer exists. Codelabs need an owner and a reason to get updated.

The other two failures pull in opposite directions. Too easy, and a new hire breezes through without ever getting stuck, which means it never prepared them for anything. Too long, and they stop. Anything past a couple of hours probably wants to be a few smaller codelabs in a sequence.

Build it the way you'd want to learn the workflow yourself. One scenario, one golden path, a starter repo, checkpoints, and a reference to compare against.

It breaks down the moment someone has to ship something. To deploy a new service, an engineer has to call the auth service, get a token, call the payments service, handle the webhook, and wire it into the deployment pipeline.

No single team’s docs cover the full sequence. The pieces are documented, but the connection between them isn’t.

What gets lost between docs

The integration patterns that connect one team’s product to another’s live in the heads of senior engineers. They learned them from pairing, from code review, from mistakes shipped to production. The knowledge is there, but it’s never written down because no team owns it.

Per-team docs don’t fix this. The auth team can’t write about how their service gets used inside the payments flow without overstepping, and the payments team can’t document the auth integration without speaking for another team. So nobody does.

The unwritten rules and best practices stay unwritten for the same reason. “Always wrap external calls in the retry helper.” Nobody owns that either, so it lives in code review comments and gets passed on by correction, not documentation.

Codelabs cover the seams

A codelab is a step-by-step exercise that walks an engineer through building something real. A starter repository, a scenario, the steps to get from empty to working, and a reference implementation to compare against.

What makes them work as internal docs is that they’re scenario-first, not product-first. A codelab pulls in whichever services the scenario requires.

A codelab on “build a service that handles webhook events from our payment provider” uses three or four internal products in one exercise. By the end, the engineer knows not just what each product does, but how they fit together in the way your company actually builds.

Where to start

If your engineers are slow to ramp up and each team’s docs look fine, the gap is probably between them. This is where a codelab earns its keep.

Pick the cross-team scenario new hires hit first, the one that usually means three weeks of asking around, and build a codelab that walks through it end to end. Keep it current as the services change.

You don’t need many. A handful covering the workflows people actually run does most of the work. The goal isn’t a codelab for everything, it’s getting people through the paths they’ll actually walk.

It rarely goes that way. Plans built on assumptions break the moment real content meets the new platform.

That’s why we don’t quote large migrations up front. We pilot first.

Why a pilot first

Planning a full migration up front assumes you can predict what the work will look like. You can’t. Not at this scale, not with content this varied.

A pilot surfaces what the plan can’t see: the issues that only appear once real content meets the real platform. Some look like minor rendering bugs. Others reshape the whole approach.

So we migrate one slice end to end. That slice might be one product in a multi-product migration, one section of a large doc set, or a single content type. The shape of the project decides the unit.

That’s enough to know what the next slice will cost, what the rest will cost, and where the work is most likely to slip.

Picking the right pilot

The slice you pick decides whether the pilot is worth running. The temptation is to start with the easiest one: smallest content, simplest structure, friendliest team. Those pilots ship smoothly and teach you nothing about the rest. Pick something closer to the average instead.

Give the pilot a deadline too. Without one, it stops being a pilot and turns into the project itself, and you lose the reason you ran it in the first place.

And when leadership wants the full scope committed before any work starts, plan with the pilot in mind. Run one slice through the full workflow first, then narrow the estimate as the project takes shape.

Evidence over estimates

Most migration projects fail in scope-setting, not in execution. The pilot is how we set scope honestly. The estimate we give for the full project is the one we earned by doing part of it.

Ship one, then scale. You’ll learn more from one migrated slice than from any plan.

Then we cross-referenced their analytics. A handful of old URLs were responsible for most of the search traffic to the site. Pages that had ranked well for years, that partners linked to, that customers had bookmarked. None of those URLs would exist on the new site.

If we’d launched without a redirect plan, they would have lost months of search traffic overnight. Customer bookmarks would break. Partner integrations would point to dead pages.

Most of the energy in a migration goes into the new platform. What it looks like, how it’s organized, what tech stack to use, where to host it… The old URLs barely come up.

But you’re not just moving content. You’re moving content that other people have linked to, in places you don’t control. Search engines, partner sites, support emails, bookmarks, internal wikis. You can’t update any of those. The only thing you can do is make sure the URLs they point to still resolve.

So if you’re planning a docs migration, ask one question: what happens to every existing URL?

Whether you’re reviewing a plan from a vendor or running the project internally, this is the check that matters. If nobody on the team can answer it, redirects aren’t going to happen. They’ll get pushed to “after launch” and never come back.

The new site can be perfect. But every old URL that breaks costs you traffic, support tickets, and a bit of trust.

It’s a fair question. Doxygen’s default output looks vintage, and most people who land on it don’t stick around.

The problem isn’t Doxygen

Doxygen is great at the part most people don’t want to do themselves: parsing code comments and extracting structured information. Class hierarchies, function signatures, parameter descriptions, return types, defaults.

The problem is what comes out of the box. The HTML looks like it was built two decades ago, and it lives as a separate site with its own search, disconnected from the docs users already know. It feels like a different product altogether.

So engineers close the tab. Writers stop pushing for it. The reference docs either don’t get published, or they get published and nobody reads them. Neither is good.

Use Doxygen as a parser, not a publisher

Doxygen also generates XML alongside HTML. Same structured data, in a format you can actually work with.

From that XML you can produce markdown, RST, or whatever format your docs platform expects. The API reference becomes part of your docs instead of a separate site bolted on. Sphinx, Docusaurus, Antora, MkDocs, whatever you’re already using.

We did this for ScyllaDB’s Driver docs. Built a custom extension that consumed the Doxygen XML and rendered it as native Sphinx pages.

The API reference now looks like every other page on the site. Same theme, same navigation, same search. When the team adds new libraries, the reference updates from the comments in the code, automatically.

The downside is that you have to write the extension if one doesn’t exist for your platform. But that’s a one-time effort, and the alternative is maintaining reference docs by hand and watching them go stale every release.

Why this matters more now

Structured API reference is also exactly what AI agents need to write correct code. When an agent has to know what parameters a function takes, or what its return type is, the reference is more reliable than any tutorial. It comes straight from the source.

Doxygen’s XML already contains all of that. Publishing it properly means it’s useful for both humans and AI, not just one or the other.

So is Doxygen going out of style?

The template is, but the tool isn’t. Doxygen still does the hardest part: extracting structured documentation from code.

Most of the tips below apply to human readers too. But they become critical when AI is retrieving your content, because the retrieval layer introduces a bottleneck. Before the LLM ever sees your content, a search or chunking system decides what to surface. A human can scan a page, skip irrelevant sections, and piece together an answer from context. A retrieval pipeline pulls a chunk and passes it forward with no such flexibility.

Here’s what we recommend:

1. Every page is page one

This was good advice before AI. Now it’s essential. Anyone landing on a page from a search result, a link, or an AI retrieval should understand what they’re reading without having seen any other page first.

Write each page so it makes sense on its own. If a page assumes the reader already knows something from a previous page, add a short explanation or a link to the prerequisite.

2. Think in questions

Users ask chatbots questions. “How do I authenticate?” “How do I export data?” “What happens if my token expires?”

Your docs don’t need to be written in question format. But the answers to these questions need to be there. Make sure your docs cover what users actually ask, not just what your team thinks is important. If you already have a chatbot running, check the logs. The questions that come up most should be clearly answered somewhere in your docs.

3. Show complete code examples

Include the full picture: imports, configuration, file paths. Humans can infer that they need to import a library if they’ve seen it before. A retrieval system often surfaces a single code block without the surrounding context, so the LLM has no way to fill in what’s missing.

4. Use consistent terminology

Pick one term per concept and stick with it. If you call it “token” in one place and “API key” in another, the retrieval layer might not connect them. LLMs are actually good at resolving synonyms within a chunk, so the real risk here is at the retrieval stage: inconsistent terms mean the right content never gets surfaced in the first place. Consistent terminology helps both retrieval and readability.

5. Less is more

Some teams try to feed everything into their chatbot: blog posts, release notes, marketing pages, changelog entries. This creates noise. When the chatbot has to search through outdated blog posts and marketing copy alongside current documentation, the odds of returning the wrong content go up.

Keep the training scope focused on current, maintained documentation. Everything else is noise that makes answers worse.

6. Avoid JavaScript-heavy rendering

If your docs site relies on client-side JavaScript to render content, some crawlers and ingestion pipelines can’t read it. Check that your content is accessible without JavaScript enabled.

7. Use keywords and metadata

Add tags, page descriptions, and front matter metadata to every page. Tags are especially useful for synonyms. If your docs use “token” but users also call it “API key” or “credential,” adding those as keywords helps retrieval systems match the right content.

8. Describe images in text

Not all AI systems can read images. If you have a screenshot showing a configuration panel, describe the key information in text near the image or using the alt text option. Same for diagrams, flowcharts, and videos.

9. One chatbot or many?

If your company has multiple products, think carefully about how to scope your chatbot. A single chatbot trained on everything tends to mix context between products and give confused answers.

That said, separate chatbots per product aren’t always the right call. If your products share APIs, concepts, or workflows, a single chatbot with good metadata and scoping rules can handle cross-product questions better than siloed bots that can’t reference each other. The key is reducing noise without cutting off useful context.

If you’re using MCP servers, set up separate servers per product and configure rules for when to use each one.

10. Keep content up to date

Stale docs produce wrong answers. When the product ships a new version, the docs need to follow.

This was always true, but now the consequences are more immediate. A chatbot trained on outdated content will confidently give the wrong answer, and users won’t know it’s wrong because it sounds authoritative.

11. Build an evaluation set

Create a list of 10 to 25 real user questions. Run them through your chatbot. Grade the answers. This gives you a baseline to measure improvements against.

Update the evaluation set as you learn what users actually ask. The questions you thought were important might not be the ones users care about.

12. Sandbox before deploying

Set up a staging chatbot alongside your production one. Test changes, new content, and prompt adjustments in staging first. Catch issues before users do.

13. Track what the chatbot can’t answer

This is the most valuable data you’ll get. Every time the chatbot says “I don’t have enough information,” that’s a documentation gap. Log these. Review them weekly.

These gaps become your docs roadmap. If users ask about webhook security and your chatbot can’t answer, that’s the next guide to write.

14. Choose a flexible platform

Technology is advancing fast. If your chatbot platform doesn’t let you configure which model to use, adjust prompts, or add restrictions, you’ll be stuck when things change. Pick a platform that gives you that flexibility.

15. Don’t wait for perfect docs

The biggest mistake we see is teams spending months preparing their docs before launching an AI chatbot. They follow every best practice, theorize about what users will ask, and wait until everything is “ready.”

Then they launch and discover the same gaps they would have found on day one.

Deploy early. See what users actually ask. Document the gaps. Watch the answers improve. Repeat. Your users will tell you what's missing faster than any internal review will.

Most docs sites are not set up for this. Some block AI crawlers by default in robots.txt and don’t know it. Others rely on JavaScript rendering that crawlers can’t see. Others have great content that buries the answer under three paragraphs of context.

Here’s what we’ve been testing and fixing across consulting projects.

Four tests to run now

Test 1: is your site crawlable without JavaScript?

Open your docs in a fresh browser. Disable JavaScript. Reload.

If the page loads and the content is readable, AI crawlers can probably read it too. If not, you have a problem. Most crawlers don’t execute JavaScript. They see what curl sees.

You can also test directly:

curl -A "ClaudeBot" https://your-docs.com/getting-started

If the response is a mostly empty HTML shell with a <script> tag, AI crawlers are getting the same empty shell.

Test 2: is your robots.txt blocking AI crawlers?

Check https://your-docs.com/robots.txt for these user agents:

GPTBot        # OpenAI
ClaudeBot     # Anthropic
PerplexityBot # Perplexity
CCBot         # Common Crawl (used by many LLMs)
Google-Extended # Google's AI training bot

If any of these are disallowed, AI crawlers are skipping your site. Some CDNs and hosting platforms block AI bots by default as part of “bot protection” settings. Worth checking.

Test 3: do you rank for questions users actually ask?

Pick three questions a developer might ask about your product. Google them with your company name.

Example: "biel.ai create account", "biel.ai docusaurus install", "biel.ai customize widget"

If you don’t rank in the first results, AI probably can’t find you either. AI retrieval uses the same signals as search engines, weighted differently. This applies both to live retrieval (what ChatGPT and Claude Code query in real time) and to training data (what the models learned from). No Google ranking usually means no AI ranking in either case.

Test 4: does your docs answer common questions up front?

Pick three common questions users ask about your product. Open the relevant docs page for each.

Is the answer on the page? Is it in the first paragraph, or buried three paragraphs deep?

AI agents retrieve a chunk of content and return an answer based on it. If your page opens with context before the answer, the agent will summarize the context instead. If the answer is missing entirely, the agent will either hallucinate or say it doesn’t know.

The 90%: indexable + useful + popular

Those four tests measure three things:

• Indexable: can AI crawlers access your content?

• Useful: does your content answer what users ask?

• Popular: is your content referenced by high-signal sources?

Cover these three and you’ve done 90% of the work.

The 10%: extra credit

We can’t know exactly which retrieval methods each AI system uses. The more signals we provide, the more discoverable our content becomes. If you’ve covered the basics and want to push further, here’s what to add.

Publish an llms.txt file. Like sitemap.xml but for LLMs. A plain text file at your site root describing what your documentation contains and how it’s organized.

# Biel.ai Docs
> AI chatbot for technical documentation

## Getting Started
- [Install in Docusaurus](https://docs.biel.ai/docusaurus)
- [Install in MkDocs](https://docs.biel.ai/mkdocs)

## API Reference
- [Authentication](https://docs.biel.ai/api/auth)

Still emerging, still evolving, but increasingly supported.

Serve markdown URLs. Crawlers and agents work best with clean markdown over bloated HTML. You can serve the same page at .md for a cleaner, token-efficient version. Example: yoursite.com/api.md instead of making them parse your HTML, CSS, navigation, and cookie banner.

Structured data and metadata. Add Schema.org markup for pricing, FAQs, and product info. Keep Open Graph tags and meta descriptions accurate. Use page metadata to describe what each page is about, including keywords and synonyms for concepts users might call by different names (e.g. “asset” vs “token”).

Publish machine-readable schemas. Make your OpenAPI specs publicly available. Same for GraphQL schemas, Protocol Buffers, or any structured contract your API exposes. Agents can parse these directly, no HTML scraping needed.

Measure where you stand

Fern’s Agent Score evaluates your docs against 22 checks covering most of the above. You get a grade and a list of issues, and a prompt you can paste into Claude Code to fix them automatically.

We ran it on our own docs and got a C on the first run. As they say, “the shoemaker’s son always goes barefoot”.

But this didn’t stop Biel.ai from ranking first when asking ChatGPT for the best AI chatbot for Docusaurus. Because we focused on the basics first.

Start with the basics

The 90% is where most of the value is. Be crawlable, improve the quality of your docs, make them popular. The extra 10% is worth doing if you’re already in good shape, but don’t skip the basics to chase it.

Most docs teams are still catching up. Start with the basics now and your docs will be easier to find when everyone else is still figuring it out.

We started following it. Within a few minutes, we had our answer. Some steps worked fine, but others didn’t even compile. One snippet referenced a method that no longer existed. Another used a dependency version from two releases ago.

The client didn’t know. The page looked great. Clean formatting, syntax highlighting, clear explanations between each code block. Nothing about it screamed “broken”, you had to actually run the code to find out.

This is what happens when code lives in Markdown files, disconnected from any build process. The docs look fine, but they just don’t work anymore.

Keep examples in a project, not in your docs

The fix: stop pasting code into Markdown files. Instead, keep your examples in a separate project that actually compiles.

The project lives in its own folder near the docs, with real dependencies, a real build step, and version control. Your docs import snippets from this project instead of containing them directly. When the product releases a new version, you update the project. If a snippet breaks, the build fails. You find out before your users do.

You can also version your examples properly. Need docs for v2 and v3? The project has branches for each. You bump the dependency, run the build, and know immediately what still works.

Once we set this up for the client, updating code examples stopped being scary. It went from editing a Markdown file and hoping it still worked to making a code change with a build. New users following the getting started guide actually got to the end.

It does mean maintaining a project alongside your docs. But the alternative is finding out your examples are broken when a user does.

If you want the practical details on how to set this up, I wrote a step-by-step guide a few years ago.

Across the industry, when companies need to reduce headcount, documentation teams are among the first on the list. Sometimes to cut costs, sometimes to justify AI investment. But the stated logic tends to be the same: AI can write docs now, so why pay people to do it?

Not every company is moving in this direction. And the ones that aren’t have a very different theory about what documentation is for.

The companies cutting writers

There are AI agents that detect code changes and draft doc updates. Tools that generate release notes, changelog entries, and API references from code and product specs. They’re fast, and for companies shipping quickly, that speed is a real advantage. On paper, you no longer need a dedicated team for this.

The question isn’t whether AI can produce docs. It’s whether it can maintain them, structure them, and make them useful over time without someone thinking about that full-time.

In practice, documentation gets reassigned to engineers or product managers, who use AI to draft it. In theory, it works. In reality, developers have already absorbed testing, infrastructure as code, CI/CD, on-call. Now add docs strategist to the pile. They have more on their plate, not less. Docs get written when there’s time, which is rarely.

Nobody reviews whether the content actually helps a user get from A to B. Nobody maintains the getting started guide when the SDK changes. Nobody decides what shouldn’t be documented.

And to be fair, there’s a real argument that the people who build the thing should document the thing. I don’t disagree. We’ve been advocating for that even before AI entered the picture. But there’s a difference between engineers contributing to docs and engineers being fully responsible for docs strategy, maintenance, and information architecture on top of everything else they already own. I’m describing a pattern I’ve seen, not citing a controlled study, but from the contracts we’ve picked up after layoffs like these, it’s consistent: the docs drift, support tickets go up, onboarding takes longer, and there’s nobody whose job it is to fix it.

Could this work with strong processes, dedicated doc sprints, or better guardrails around AI-generated content? Maybe. I haven’t seen it succeed at scale yet, but I’d welcome examples that prove otherwise.

The companies investing in writers

On the other side, some companies are hiring more writers, not fewer, and using AI to augment them. Their reasoning: documentation is now the source material that every AI system depends on. AI coding assistants, chatbots, support agents. They all consume your docs. If the docs are wrong, the AI is wrong.

Here’s a concrete example. An AI coding assistant trained on outdated API docs will confidently suggest deprecated endpoints and wrong parameter names. Developers follow the suggestion, hit errors, file issues, and lose trust in the tool. The root cause isn’t the AI. It’s the docs the AI was reading.

These companies treat documentation as infrastructure. The foundation for how users and AI understand their product. The better the docs, the better every experience built on top of them.

Anyone who’s actually used AI to write or code knows it’s a back and forth. You prompt, you review, you correct, you re-prompt. The output needs judgment. Someone who knows what good docs look like, not just someone who can generate more of them.

But it’s not just about producing docs. There’s also a role AI can’t fill, at least for now. Technical writing has never been 100% writing. It’s deciding what gets documented and what doesn’t. Knowing who to ask for the right information. Evaluating whether docs are useful or need rework. Figuring out what order things should be learned in. And knowing when adding more pages actually makes things harder to find. An AI will happily generate pages for everything. A good docs team knows when to say no.

Where I stand

I run a documentation engineering consultancy. I have skin in the game, and I’ll be honest about that. We’ve had contracts cancelled because companies decided AI could handle the docs. We’ve also gained contracts from companies that understand docs are the fuel for AI.

Our position: AI makes writers more capable, not redundant. Writers who use AI to draft, then edit, verify, test, and structure produce better output than before. Maybe the companies that cut their teams had other reasons for making that call. But creating better docs wasn’t one of them.

The companies investing in documentation right now understand something simpler: every answer AI generates is only as good as the docs it’s reading.

The assistant kept responding “I couldn’t find information about this” for basic things. Export data. Reset password. Delete account.

Support had been answering these verbally for years. Everyone assumed it was documented, but it wasn’t.

Why basic flows go undocumented

When a team ships something new, they want to document the shiny parts. The feature they spent months building. The complex integration that’s hard to understand without a guide.

Nobody writes a page about how to reset a password. It feels too obvious.

Then support starts getting questions. They answer them in 30 seconds over chat, and writing a whole doc page for that feels like overkill. So it stays verbal. Months pass, new support agents join, and they learn the answers from colleagues, not from docs. At some point everyone just assumes it’s written down somewhere.

An AI assistant breaks this cycle. It can only answer what’s documented. It doesn’t know what support told a user last week, and it doesn’t have access to Slack threads or old tickets. In our case, that’s intentional. We only train it on curated, reviewed documentation.

So when a user asks “How do I export my data?” and the assistant says “I couldn’t find information about this,” that gap is no longer invisible. It shows up in the logs, every day. You can’t ignore it.

Use the gaps

Once we documented the missing flows, tickets dropped. The assistant started answering questions it couldn’t before.

But here’s the part we didn’t expect: the “I don’t know” responses told us exactly what to write next. We just looked at what users asked most and started there.

AI assistants don’t fix documentation problems. They make them visible.

The client said it casually, like it was just how things worked. The system rebuilt the entire site every time, even for a one-word fix.

This is more common than you’d think, and it kills documentation quality in ways that aren’t obvious.

Slow builds make docs worse

When a build takes 30 minutes, nobody verifies small changes. You fix a typo, push it, and hope for the best. You’re not going to wait half an hour to check whether the formatting looks right.

So writers stop iterating. They batch changes into big updates instead of making frequent small improvements. Reviews drag because nobody wants to trigger another long cycle just to see a preview.

The result: fewer updates go out, more errors slip through, and the team starts treating the docs as something to avoid touching.

Why this build was slow

The project used Sphinx, and every build generated everything from scratch: the full HTML site and a complete PDF manual.

The PDF was the bottleneck. Sphinx uses LaTeX to produce PDFs, and LaTeX is slow. One monolithic PDF meant one monolithic build, so changing a single paragraph in the authentication guide rebuilt a 1,400-page PDF from scratch.

It got worse: the HTML and PDF builds ran one after the other. Even when the HTML build was fast, it sat waiting for the PDF to finish before the pipeline completed.

What we changed

We split the monolithic PDF into separate files, one per section. Authentication, API reference, deployment guide, each with its own PDF. Now changing the auth docs rebuilds only that PDF and leaves the rest untouched.

Then we stopped running the two builds in sequence. HTML and PDF now build in parallel, so writers can preview their HTML changes right away while the PDFs generate in the background.

The result

Build time dropped from 30 minutes to under 5 for most changes.

But the number isn’t the point. What mattered was how the team’s behavior changed. Writers started checking their work again. Small fixes went out the same day instead of waiting for “next sprint.” Reviews sped up because previews were ready in minutes. The docs got better because the build time got out of the way.

Nobody complains about slow builds in sprint retros. They're a silent documentation killer, quietly pushing teams away from touching the docs.

If yours takes more than 10 minutes, it's worth finding out why.

Two years ago, they’d open your docs site and read the guide. Today, they type “How do I authenticate with this API?” in Claude Code. The AI answers, writes the code, and moves on. Your docs site never sees a pageview.

Some engineers at Anthropic and OpenAI report that AI now writes 100% of their code. If developers aren’t writing much of the code themselves, they’re certainly not browsing your docs to figure out how to write it.

We’re seeing this in the documentation projects we work on. AI-driven traffic to docs sites is growing while human visits drop. Mintlify reports that almost half of documentation site traffic now comes from AI agents, not humans. Your docs have a new primary reader, and it doesn’t browse. It queries.

From reading to asking

Documentation always competed with Stack Overflow, GitHub issues, and asking a coworker on Slack. AI coding assistants just won that competition. When you can describe your problem in natural language and get working code back, in context, inside your editor, there’s no reason to open a docs site.

But that doesn’t mean docs matter less. If anything, accuracy matters more now. A human reading a confusing paragraph will slow down, re-read, maybe search for other sources. An AI will pick an interpretation and ship it.

The problem with public AI models

When a developer asks an AI about your product, the model either relies on training data or searches the web, and both are broken.

Training data is stale. If you shipped a new SDK version last month, the model doesn’t know, and it’ll suggest deprecated methods with full confidence. Web search relies on SEO, so the model might surface a three-year-old Medium article instead of your current API reference. Your discoverability depends on how well you rank, not on how good your docs are.

Neither approach has any special relationship with your documentation. The model doesn’t know your custom error codes or the migration guide you published last Tuesday. So it generates code based on outdated examples and wrong parameter names, and the developer doesn’t find out the answer was wrong until something breaks.

It gets worse for internal docs

If public docs have a discoverability problem, internal docs are completely invisible.

Your internal wiki, your Confluence spaces, your private Notion pages. AI models can’t see any of it. A new engineer joins your team, asks their AI assistant “How do I deploy to staging?”, and gets nothing useful. The model wasn’t trained on your deployment runbook, and it can’t search your internal network. Every AI tool your developers use daily is blind to the documentation they need most.

Connect your docs to the tools developers actually use

There’s a fix. Instead of hoping AI models happen to find your docs, you can connect your documentation directly to the AI tools developers already use.

This is what the Model Context Protocol (MCP) enables. It’s an open standard that lets AI assistants connect to external data sources, a bridge between an AI coding assistant and your documentation. With an MCP server pointing at your docs, the assistant fetches answers directly from your content in real time, not from training data and not from Google.

The part worth understanding is how the assistant decides when to use it. You register a description of what your docs contain, and the AI uses that description to decide when to query them. If a developer is working with your SDK and hits an authentication problem, the assistant knows your docs are the right place to look. It isn’t a keyword search. The AI decides based on context.

What this means for documentation teams

Your docs go from a website people browse to a data source AI tools query, and that shifts what matters.

Content quality counts for more, not less. Every ambiguity, every outdated example, every missing step gets amplified, because bad docs now produce bad AI answers at scale. Good docs produce answers that make developers trust your product.

Internal docs become reachable too. That deployment runbook, your team’s coding standards, your architecture decision records: MCP can expose them to AI assistants inside your organization.

And you get better feedback than pageviews ever gave you. When AI assistants query your docs, you can see what questions are being asked, which is direct signal about what developers are actually trying to do.

What this doesn’t fix

MCP doesn’t fix bad docs. If your content is incomplete or outdated, AI will serve incomplete, outdated answers, just faster.

It doesn’t eliminate hallucinations either, though it gets things wrong less often when it has access to the right content. Your docs site is still the canonical source of truth. When AI gives a wrong answer, that’s where developers go to verify. MCP just makes your content reachable from more places.

Where to start

Start thinking about how AI assistants consume your content, not how humans read it. Structured content, clear headings, explicit examples: these matter even more when your new reader parses pages instead of browsing them.

Then look into how MCP can work for your docs. Connect it to the tools your team already uses, and see what questions come in.

Your docs are already being consumed by AI. The only question is whether you’re serving the right answers or letting the model guess.

It was working fine. Four years ago.

A client called recently about their docs site. Sphinx four versions behind, dependencies with known security vulnerabilities, deprecated extensions holding the build together, a theme broken on current browsers, and search that had grown noticeably slower.

The launch got budget. Content creation got budget. Someone even set up CI to build and deploy automatically. The team celebrated, then moved on.

Framework upgrades, dependency updates, security patches? Nobody brought them up. There was no line item for “keep the docs site alive,” because it was alive. It was working fine.

Your docs site didn’t break

You just stopped keeping up with everything around it.

Every dependency you don’t update becomes a risk. Every framework version you skip makes the next upgrade harder. None of it is urgent on any given day, and all of it is urgent four years later.

The decay is invisible. The site loads, the search works, the pages render, until one day they don’t. Or they do, just slower, just slightly broken, just enough for users to notice before you do.

The cost equation

Keeping a docs site maintained is routine work. Not always simple, but manageable if you stay current. The problem is that it never wins against everything else on the roadmap.

The actual cost is modest. A few hours a quarter to update dependencies, a CI check for broken links, an annual framework upgrade before you fall too far behind. Call it 20 to 30 hours a year.

Compare that to what neglect cost this client. Their docs were broken for at least three months before anyone flagged it, and the fix took another six weeks. Four and a half months of slow search and a theme that looked off on half the browsers visiting it. All that time, the docs were quietly telling users that this company doesn’t maintain its tools.

Your docs site is a production system

We all understand this for apps. Nobody ships a production app and walks away for four years. There are monitoring tools, dependency bots, upgrade cycles. A docs site has users, dependencies, and security surface area too. It deserves the same care.

Docs sites get none of that. They get launched and forgotten. Then someone calls you four years later wondering why everything is broken.

It has users, dependencies, and security surface area. It deserves the same care.

That client's site is fixed now, and they're on a maintenance plan. The kind of work that never makes headlines, but means nobody has to make that call again.

The review process was supposed to be simple: build the docs locally, check for broken links, formatting issues, rendering problems, then approve.

Except reviewers weren’t building the docs locally. They were skimming the markdown in the PR and hitting approve. “LGTM!” Without ever seeing the rendered output.

You can’t really blame them. Building docs locally means cloning the repo, installing dependencies, running a build command, waiting, then navigating to localhost. That’s five minutes of friction for a review that “should” take two. So they skip it and hope it renders fine.

This isn’t a discipline problem

It’s a friction problem.

We don’t skip important steps because we’re lazy. We skip them because the effort feels disproportionate to the task. A quick review shouldn’t require a local dev environment, but this one did. So the “quick review” quietly became “skim the markdown and approve.”

The fix was simple

We added automated PR previews. Every pull request now generates a deployed preview and drops the link in the PR comments.

“Click this link” replaced “build it locally.” One click versus five minutes of setup. Guess which one people actually do.

Review quality went up immediately. Not because we trained anyone, not because we wrote stricter guidelines, not because we added more process. We just removed the friction.

The pattern

This isn’t unique to doc reviews. Style guides get ignored when checking them by hand is a chore, so you put the linter in CI and suddenly everyone complies. Broken link checks never happen because clicking every link is tedious, so you automate them and they get caught before merge.

The step is important. Everyone agrees it’s important. We still skip it, and every time the reason is the same: too much friction for the value it delivers in the moment.

So instead of asking “why aren’t people following the process?”, ask “what’s making this process hard to follow?”

If you've run into something similar (a process that kept getting skipped until you found a way to reduce the friction) I'd love to hear about it in the comments.

That’s a fine goal. But it misses the bigger opportunity.

The real value isn’t answers. It’s visibility.

Every question a user asks reveals something:

• A confusing explanation

• A missing example

• A gap in the product itself

When teams add an AI assistant to their docs, they don’t just get faster support. They get a window into exactly where users are struggling.

When your AI can’t answer, that’s not a failure. It’s a signal.

That shift changes everything.

From static reference to feedback loop

Traditional documentation is a one-way broadcast. You write it, publish it, and hope it helps.

But when you track what users actually ask, documentation becomes a conversation. You see patterns. You spot the same confusion appearing again and again. You find the blind spots your team never noticed because you’re too close to the product.

Suddenly, your docs aren’t just supporting users. They’re teaching you what to fix.

The insight you’re leaving on the table

If your documentation only answers questions, you’re capturing maybe 10% of its potential value.

The other 90%? It’s in the questions themselves.

• Which features confuse people most?

• Where do users get stuck in onboarding?

• What terminology doesn’t land?

With an AI assistant, that data exists. Most teams just aren’t collecting it.

A good AI assistant surfaces which questions your docs can’t answer, ranked by frequency.

From insight to action

Knowing where the gaps are is only half the problem. Fixing them is where most teams stall.

The best tools help you close those gaps with clear guidance on where to start.

Start here

Next time you look at your docs, don’t ask “did we cover everything?”

Ask “what are users still asking, and why?”

The answer will show you exactly what needs to change.

“Hey, can you review this?”

Two days later I had 10 comments. Four were about commas. Two more debated whether colons introducing lists should be bold. Another spent three paragraphs on whether “setup” should be one word or two.

Not a single comment mentioned that step 4 was completely broken. The command I told users to run didn’t actually work.

Why vague requests produce surface feedback

When you ask “can you review this?” with no direction, reviewers default to whatever stands out first: typos, formatting, word choice. Easy to spot, easy to comment on.

“Review this” could mean:

• Check if the logic makes sense

• Verify the code runs

• Look for security issues

• Test the user flow

• Proofread for typos

• Check if the tone is right

Without knowing what you need, people pick the easiest path.

The cost of unfocused reviews

You spend hours sorting through comments that don’t help. Reviewers spend their energy on things you’ll ignore or fix in a later phase. And the real issues never get caught.

I’ve watched teams spend three review cycles debating admonition colors while nobody noticed the registration flow was broken. Product and docs ship, users can’t sign up, and someone says “but we had five people review it.” They did. They reviewed the wrong things.

How to ask for useful feedback

Tell exactly what to look at:

• “Does the getting started flow make sense?”

• “Are the code examples working on your end?”

• “Is the reference documentation for this function complete?”

And tell them what to ignore:

• “Don’t test authentication, QA is handling that”

• “Ignore formatting, I’ll run the linter”

• “Skip the intro section, it’s placeholder text”

• “Don’t worry about performance yet, that’s next sprint”

The second half matters as much as the first. Telling people what to skip is what frees them to focus on what you actually need.

If you’re the one being asked to review

This works the other way too. Someone sends you “can you review this?” with no context. Ask what kind of feedback they’re looking for. It takes 30 seconds and saves you both from a useless cycle.

Ask “What kind of feedback are you looking for?”

Takes 30 seconds. Saves both of you from a useless review cycle.

That doesn’t mean ignoring obvious problems. If you spot a bug or a broken link while reviewing, point it out. If something’s unclear, say so. Leave things better than you found them. But keep the goal in mind: if someone asked you to review the tutorial flow and you spend 15 minutes hunting for Oxford commas, you’ve lost the plot.

How to make this normal

Next time you ask for a review, add one specific question. When someone asks you to review something, ask what they’re looking for.

A simple template helps:

• What changed: brief summary

• What to focus on: specific concerns

• What to skip: things handled elsewhere

• Questions: what you’re unsure about

What it comes down to

Everybody wants to help. But without direction, it’s easy to lose focus on whatever jumps out first, and that’s almost never what you need.

If you want useful feedback, ask useful questions. Be specific, point toward what matters, and call out what to ignore. You’ll get faster reviews, better feedback, and fewer arguments.

Most documentation disasters come from organic growth. One team adds a page here, another adds one over there, and nobody is thinking about the whole. Structure only becomes a concern after hundreds of pages exist, by which point nothing is easy to find.

The pattern is always the same: content, then more content, then nobody can find anything. Then someone finally asks “should we reorganize this?” when reorganization means touching 300 pages and breaking every bookmark and search result.

Strategy → Structure → Content.

Not Content → More Content → Chaos.

What documentation strategy actually means

Strategy doesn’t mean a 40-page plan. It means answering a few critical questions before anyone writes a word.

Who are you writing for?

Not “developers.” That’s too vague. Define specific personas in specific situations. A developer integrating your API under deadline pressure needs different content than an enterprise architect evaluating your security model. Pick a primary audience. Acknowledge the others exist, but know who you’re optimizing for.

What job is each piece of documentation doing?

Documentation serves different purposes:

• Teaching a concept through example (tutorial)

• Solving a specific problem (how-to guide)

• Looking up syntax (reference)

• Understanding why something works this way (explanation)

These aren’t interchangeable. A reference doc won’t teach a beginner. A tutorial won’t help someone troubleshooting at 2am. Your strategy needs to decide which jobs matter most for your product and your users, then commit to doing those jobs well.

What’s the minimum content that unlocks the product?

You don’t need comprehensive API docs on day one. You don’t need advanced guides for features nobody’s using yet. You need whatever removes the biggest obstacle between a new user and their first success.

Everything else can wait. The question isn’t “what should we document eventually?” It’s “what’s blocking someone right now?”

What should each page cover?

Once you know which content types you need, define what makes each one complete. Tutorials should list prerequisites up front and guide users to a working example. API references need request examples, response formats, and error codes. How-to guides should state the outcome at the start and show the steps clearly. Explanations need context on why things work the way they do.

This is where templates help. They ensure consistency and completeness across your documentation. But templates only work after you’ve defined your strategy. Without clarity on what each page type requires, templates just give you consistently incomplete content that raises more questions than it answers.

The early content trap

In practice, you can ship some early content while doing this thinking. You should, even. But those quick wins shouldn’t define the strategy.

You’ve seen how this goes. You ship a tutorial because five users asked for it, then a troubleshooting doc because support is overwhelmed, then someone adds an FAQ, then best practices. Each one makes sense in isolation. None of them were planned together. Six months later you have 50 pages organized by the order they were written, not the order anyone needs them.

A strategic early win looks different. You know it’s one piece of a larger system. You know where it lives, and what comes before and after it. Even if you haven’t written those other pieces yet, you’ve left room for them.

It’s the difference between “we need a tutorial, someone write it” and “we need a tutorial that assumes zero prior knowledge, gets someone to a working integration in under 10 minutes, and hands them off to either the API reference or advanced tutorials depending on what they want to do next.” Same deliverable, completely different foundation.

What changes when you do this right

The writing gets faster, because you’re not reinventing structure with every new page or second-guessing where something belongs.

Maintenance gets easier, because when the product changes you know exactly which docs need updating and how the pieces relate.

Users find what they need, not because your search is amazing but because the structure matches how they think about problems. A

nd new contributors can add content confidently, because the system makes it obvious where things go.

None of this happens if you start with content and hope structure emerges. Structure rarely emerges on its own. Chaos does.

How to start

You don’t need perfect answers to those strategy questions. You need good-enough answers and permission to revisit them.

Spend a week, maybe two. Talk to five users about what they’re trying to do. Look at your support tickets to see what’s actually confusing people. Then sketch the 10 to 15 core topics your documentation needs to cover and how they connect.

The approach I use is to map navigation flows for each persona first. Where does a junior developer enter your documentation? What’s their path to first success, and what do they need next? Where does a senior architect start, and what questions do they need answered to evaluate your product? Sketch these journeys: where each audience enters, what they read, and where they go when they’re stuck.

Example navigation flows for two different personas. Use it to identify key content and paths.

These flows reveal what content you actually need, not just what seems logical to document, and they give you your structure.

Structure isn’t about folders. It’s about reflecting how users think about your product. If they think in workflows, organize by workflow. If they think in features, organize by feature. Don’t organize by how your engineering team structured the codebase, because nobody outside your company thinks that way.

Then build a grid in a spreadsheet, one row per page or section you think you’ll need. Give it columns for the page title, the persona it serves, the content type (tutorial, reference, how-to, explanation), the priority (must-have for launch, nice-to-have, future), and a short description of what the page covers.

Columns for:

• Module / page title

• Persona: who is this for?

• Content type: tutorial, reference, how-to, explanation

• Priority: must-have for launch, nice-to-have, future

• Description: Brief description of what the page covers, required subheadings.

The grid forces you to think about the whole system at once instead of page by page. You’ll spot gaps (”wait, we have five reference docs but no how-tos?”) and redundancies (”these three pages are basically the same thing”).

One thing I’ve found useful: identify your action-oriented content first, the tutorials and how-to guides, then build reference and explanation docs around them. Those supporting docs can be referenced from multiple guides, so you’re not repeating the same API details in every tutorial. The guides stay focused on the task while the depth lives somewhere reusable.

Together, the flows and the grid become your roadmap. When someone asks “should we document X?” you can see where it fits, or doesn’t. When priorities shift, you adjust the plan instead of 47 individual pages.

Then you start writing. But now you’re writing into a framework, not into a void.

Strategy doesn’t slow you down. It’s what makes fast sustainable.

Planning your documentation strategy?

If you’re staring at documentation chaos or launching something new and want to avoid building problems into your foundation, we can help.

We work with teams to design content architecture that scales: mapping personas, defining structure, and creating the roadmap before anyone writes a word.

2025 was full of growth and learning.

At TechDocs Studio, we helped clients build scalable documentation infrastructure, automate workflows, and improve their docs, seeing firsthand how targeted improvements transform daily work for teams.

We also reinvested in our own products, including Biel.ai and PushFeedback, tackling common documentation challenges our customers face. Watching these tools start to make a real difference has been incredibly rewarding.

This year reinforced that growth is not just about new contracts, but about trust, collaboration, and celebrating small wins together.

I’m grateful to everyone who made this year possible:

• 𝗖𝗼𝗿𝗲 𝘁𝗲𝗮𝗺: Àlex, Raúl. Thank you for bringing skill, dedication, joy to every project.

• 𝗡𝗲𝘄 𝗰𝗹𝗶𝗲𝗻𝘁𝘀: Kristy-Leigh, Matthew, Rustom, Alex, Jimmy. Thank you for trusting us.

• 𝗟𝗼𝗻𝗴-𝘁𝗲𝗿𝗺 𝘀𝘂𝗽𝗽𝗼𝗿𝘁𝗲𝗿𝘀: Anna, Tzach, Elena, Jorge, Alberto, Rich, Nate. Thank you for your continued trust and support over the years.

• 𝗘𝗻𝗮𝗯𝗹𝗲𝗿𝘀: Pablo, Juan Luis. Thank you for connecting us with exceptional people.

• 𝗙𝗲𝗲𝗱𝗯𝗮𝗰𝗸 𝗰𝗵𝗮𝗺𝗽𝗶𝗼𝗻𝘀: Lars, Tim, Harshil, Seonaid, Elena K. Your feedback improved our tools for everyone.

• 𝗜𝗻𝘀𝗽𝗶𝗿𝗮𝘁𝗶𝗼𝗻: Ivan, Sabela, Cristina, Aleix, Xavi. I’ve learned a ton from all of you.

• 𝗢𝗽𝗲𝗿𝗮𝘁𝗶𝗼𝗻𝗮𝗹 𝘀𝘂𝗽𝗽𝗼𝗿𝘁: Davinia for keeping our finances in order, Gonzalo for managing customer relations.

...and to everyone we worked with behind the scenes, thank you for your support.

If you’re curious about what we built in 2025, you can explore our projects at techdocs.studio/work:

Aligning Coiled’s documentation theme with their brand identity

Following the successful launch of Coiled’s new website, we developed a custom Sphinx documentation theme that aligned with their updated brand identity, ensuring a cohesive user experience across docs.coiled.io and the main marketing site.

Read case study

Custom Sphinx theme development for FiftyOne documentation

We upgraded FiftyOne’s documentation from Sphinx 3 to the latest version, created a custom theme aligned with the new Voxel51 brand guidelines, and implemented advanced search capabilities with PushFeedback integration for continuous improvement.

Read case study

From Webflow to Next.js: Creating a developer-first website for Coiled

Migrated Coiled’s website from Webflow to a modern, component-based static site generator, empowering their team to manage content like they manage code.

Read case study

Automating API reference generation from OpenAPI and GraphQL schemas

Migrated MONEI’s docs to Docusaurus v3, implemented cross-site search, and autogenerated consistent API documentation from OpenAPI and GraphQL contracts.

Read case study

Unifying Blue Robotics’ documentation with a custom Sphinx theme

Developed a custom Sphinx theme with Material design aesthetics, implemented multi-language support, and set up a custom CI/CD pipeline for version management across their documentation ecosystem.

Read case study

Here’s to 2026: more learning, more impact, and helping teams build documentation that scales!

— David

We suggested adding a feedback widget. A small button: “Was this helpful?”

One week later, 12 users had left feedback. Not one was positive.

“Step 3 is missing.” “This example doesn’t work.” “I’ve read this four times and I’m still confused.” “Where’s the actual code?”

Those 5 minutes weren’t engagement. They were users scrolling up and down, re-reading, trying to figure out what was missing.

Good metrics, bad experience

The analytics showed what users did. The feedback showed why.

The team fixed everything in 48 hours: added the missing step, replaced the broken example, clarified the confusing parts, and added code where users expected it.

Session time dropped to 3 minutes. But now users were finishing successfully instead of giving up confused.

You need both

Quantitative data shows behavior. Qualitative data explains it.

Your analytics will tell you users spent 5 minutes on a page. Your users will tell you they spent those 5 minutes confused.

One number can mean two completely different things.