Eventually, the same navigation is serving products with different audiences, owners, and release schedules. Reorganizing the links is no longer enough. You need to decide what the documentation should still share.

Here are five ways to structure it, from one shared sidebar to separate sites connected by a common hub.

1. One sidebar for multiple products

One sidebar can support several products when they belong to the same workflow and serve the same audience.

Readers can move between products without returning to a portal. For the documentation team, it also means one search index and navigation model.

Docker Docs shows the pattern clearly. Its global sidebar includes Docker Desktop, Engine, Offload, Build, Build Cloud, Compose, Hub, Scout, and other products. They share one navigation because they support a connected workflow: develop locally, build container images, define multi-container applications, share images, and check their security.

The length of the sidebar matters less than whether its categories make sense to the same reader. Split the experience when product teams need different structures or readers regularly encounter irrelevant sections.

2. Shared documentation with language-specific code

SDKs for Ruby, Python, Java, Node.js, Go, and .NET may look like separate products internally. To the reader, they are often different ways to complete the same task. Publishing a complete guide for each SDK duplicates the prerequisites, warnings, and troubleshooting.

Stripe’s server-side SDK documentation keeps the task and explanation shared while letting readers select the language used by installation instructions and code examples.

This works when the goal and sequence stay the same and only the code, package names, or small technical details change. Create separate doc sets when setup, concepts, or constraints also diverge. A mobile SDK and a server SDK may share a brand but still need different user journeys.

3. Shared documentation with a page-level variant selector

Sometimes the reader needs more than a different code sample. The same task may have different steps for a cloud plan, an enterprise edition, or a self-managed release.

If most of the explanation is shared, a page-level selector can carry that context across the site. The reader chooses once, and the documentation shows the relevant pages, steps, and navigation.

GitHub Docs uses a selector at the top of the page. Readers can switch between Free, Pro, and Team, GitHub Enterprise Cloud, and supported GitHub Enterprise Server releases. The selected context becomes part of the URL and controls which content appears.

GitHub maintains these variations from a single source using metadata and conditional content, as described in its versioning documentation. This works when every edition can still share one information architecture, but the instructions differ often enough to distract readers.

When only a few procedures differ, the selector can stay local to those sections. Camunda’s API documentation uses SaaS and Self-Managed tabs to change authentication steps and commands without changing the surrounding page.

If each variant needs different navigation, ownership, or release workflows, a selector may be hiding a larger architectural split.

4. Separate product areas within one documentation site

Some products belong to the same platform but need different documentation structures. Putting both in one sidebar would mix concepts, setup paths, and reference material that only apply to one product.

PlanetScale’s documentation gives Vitess and Postgres their own entries in the top navigation. Selecting either product opens a focused documentation area with its own sidebar. Shared platform, API, and CLI documentation remains available from the same header.

This is easier to navigate than a product directory when there are only a few clear choices. Each product can have its own information architecture while the company keeps one documentation domain, search experience, and visual system.

For a larger catalog, the same idea needs another layer. Cloudflare’s documentation directory adds search, product descriptions, and category filters before readers enter product-specific documentation.

At that scale, product names alone are not enough. The directory needs descriptions, categories, synonyms, and task-oriented routes for readers who know their problem but not the product that solves it.

5. A hub connecting federated documentation sites

Separate sites make sense when products within the same company have distinct brands or audiences, or when different teams own them and need autonomy over their documentation. Each team can shape its site around its product and users. A central hub explains how the products relate and gives readers one place to start.

We built this model for ScyllaDB. ScyllaDB Cloud, the database server, drivers, Operator, Monitoring Stack and Migrator can keep their own documentation and release processes. The central portal gives readers one place to begin.

In this case, the architecture follows the ownership model. Product teams maintain documentation close to their code, while shared theme packages and integrations make the sites feel like one system. Our ScyllaDB case study describes this “docs in tree” approach in more detail.

A federated model still needs shared theme packages, cross-site search, analytics, metadata, and an owner for the hub. That platform work is justified when forcing autonomous teams into one repository would create more coordination than it removes.

Which multi-product documentation architecture should you choose?

Before choosing a pattern, answer four questions:

1. Audience: Do the same people use these products in the same journey?

2. Ownership: Does one team maintain the documentation, or do product teams need autonomy?

3. Release cadence: Can the content build, version, and publish together?

4. Overlap: Is most of the content shared, or only the brand and visual design?

Use the simplest option that matches those answers. If the same audience and team can navigate and maintain the content, keep it together. Split the experience when readers or owners need a clearer boundary.

If you are reorganizing an existing site, run a pilot project before committing the full documentation set to the new structure.

How are you organizing documentation across products? Reply and tell me what’s working and what isn’t.

It worked for one hire. As the company grew, the team repeated the same walkthrough every time someone joined. The result depended on who was available and what they remembered to explain. Two people joining in the same month could receive very different introductions to the same system.

The person leading the onboarding also lost days repeating work they had covered with the previous hire.

I led a codelabs program at a large enterprise to make this process repeatable. Here’s how we approached it.

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

Pairing still mattered. Senior colleagues provided context, answered difficult questions, and explained the decisions behind the system. But much of the initial setup followed the same path every time.

When that path lived in someone’s head, each mentor taught it differently. One remembered an important step. Another skipped it. One explained the complete workflow. Another assumed the new hire would pick it up later.

Codelabs captured the common path. New hires could work through the basics independently, while mentors remained available for questions that required context or judgment.

Start with the work new hires actually do

We listed the tasks a new hire handled in the first few weeks and used those to scope the documentation. The org chart stayed out of it.

New hires ran many of the same workflows regardless of team. Those workflows crossed several systems and ownership boundaries, where reference docs leave gaps tends to leave gaps.

A small set of codelabs covered the most common first-month tasks. Each one focused on a path that new hires would actually follow.

Use the same structure every time

Every codelab followed the same structure: a real scenario, a clear starting point, one supported path, checkpoints, and a reference solution.

When a thousand people work through the same exercises, they need to know what to expect. A common format also makes the codelabs easier to review and maintain.

I covered this structure in what makes a good codelab in a previous post.

What changed

The first task no longer took three weeks. New hires could follow the documentation and ship their first change without waiting for a senior engineer to walk them through it.

Mentors spent less time repeating setup. Everyone completed the same exercises, so the team also gained a shared baseline. When someone said, “I did the onboarding codelab,” everyone knew what they had learned.

The documentation handled the repeatable parts of onboarding. Mentors could focus on questions that needed context, judgment, or experience.

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.

These are the checks we make first.

1. Write sections that survive retrieval

A reader sees the page around a paragraph. A documentation assistant may receive only that paragraph and its heading.

Make each section understandable when it is retrieved on its own. Name the product, feature, or task in the heading. Restate prerequisites that change the meaning of the instructions. Replace headings such as “Configure it” or “Next steps” with headings that say what is being configured and what happens next.

You do not need to repeat the whole page. You need enough context for one section to remain accurate after it has been separated from the page.

2. Start with real user questions

Support tickets, site search terms, sales calls, and assistant logs show how people describe their problems. Use that language to check whether the docs contain a direct answer.

The page does not need to use a question as its title. It does need to cover the question users actually ask. “Authentication” may be a tidy section name, but users are more likely to ask why their token expired or how to rotate a key without downtime.

3. Show the complete procedure

Code examples need imports, configuration, file paths, and any setup required to run them. Procedures need prerequisites, expected results, and the important failure cases.

This matters because the assistant may retrieve the code block without the paragraph three sections earlier that explains where it belongs. A complete example gives the model fewer gaps to fill and gives the reader something they can verify.

4. Use one term for each concept

Choose a preferred term and use it consistently. If “API key,” “access token,” and “credential” mean different things in your product, the docs should make that distinction clear.

Keep known synonyms in a glossary, redirects, search configuration, or retrieval metadata when your system uses them. Do not scatter synonyms through the prose only to improve matching. That makes the documentation harder to read and can blur distinctions the assistant needs to preserve.

5. Curate what goes into the index

Do not add every page you own by default. Marketing pages, old release notes, duplicate migrations, archived versions, and internal drafts can compete with the current documentation.

Decide which sources are authoritative for each product and version. Exclude duplicate or obsolete content unless users still need it, and label historical material clearly when you keep it. This is indexing or retrieval scope, not model training.

6. Make versions and applicability obvious

A correct answer for the wrong version is still a wrong answer.

State which product, version, deployment model, plan, operating system, or SDK a section applies to. Put that information close to the instructions instead of relying only on a selector elsewhere on the page. When the same procedure covers several variants, say what changes for each one.

Archive or redirect unsupported versions when possible. If older documentation must remain available, keep it clearly separated from the current set.

7. Preserve context when pages are split into chunks

Most retrieval systems divide a page into smaller chunks before indexing it. A section called “Limits” becomes ambiguous if the chunk no longer carries the page title, heading path, product, or version.

Inspect the content after ingestion as well as the source page. Each chunk should retain the context needed to identify it. That may include the page title, parent headings, product, version, and a short description of what the section covers.

Anthropic describes a related technique in its guide to contextual retrieval: adding chunk-specific context before content is indexed.

8. Use metadata for decisions the system can enforce

Metadata is most useful when the retrieval layer can filter on it. Product, version, deployment model, audience, lifecycle status, and access level are practical fields because they can stop the wrong source from reaching the model.

Do not add tags and assume they improve retrieval automatically. Confirm that the ingestion pipeline preserves them and that search applies them. For example, OpenAI’s retrieval tools support attribute filtering before semantic search.

9. Keep important information in text

Some models can interpret screenshots and diagrams, but documentation pipelines do not all ingest them in the same way. A critical instruction that exists only inside an image is easy to lose.

Explain the required action, value, or decision in the surrounding text. Use alt text to describe the purpose of the image, and add a caption when the reader needs context. For a diagram, summarize the relationship or sequence the diagram is meant to show.

10. Give the ingestion pipeline a clean source

Find out what the assistant actually reads. It may crawl the published site, ingest Markdown from a repository, use an API, or receive selected resources through an MCP server.

If it crawls the site, make the main content available as clean HTML and use stable, crawlable URLs. Google can render JavaScript, but it still recommends server-side or pre-rendering because not every bot runs JavaScript. If the assistant ingests the repository instead, test the generated text after parsing and remove navigation, cookie banners, and other page furniture.

11. Scope by product, version, and access

One assistant can cover several products when the system can identify the user’s context and filter the sources reliably. Separate assistants or MCP servers make more sense when the products have different owners, audiences, or access boundaries.

Do not split the system per product as a reflex. First decide which content a user should be able to reach and which questions genuinely need information from more than one product. For restricted MCP resources, apply authorization and least-privilege access. The official MCP guidance recommends scopes tied to specific tools or capabilities.

12. Require sources and a safe fallback

An answer should point back to the documentation that supports it. Source links let readers check the details and help your team diagnose why an answer went wrong.

Decide what the assistant should do when the evidence is missing, conflicting, or outdated. A clear “I couldn’t find this in the documentation” is more useful than a plausible guess. It should also tell the reader where to go next, such as support, a product owner, or the relevant documentation area.

13. Build an evaluation set from real questions

Collect questions from support, search, onboarding, and assistant logs. Include common tasks, edge cases, ambiguous wording, version-specific questions, and questions the assistant should refuse to answer.

For each question, record the expected source and the criteria for an acceptable answer. Keep the first set small enough to review by hand, then add new cases as users expose gaps. OpenAI’s evaluation guidance for Q&A over documentation recommends combining production data, expert-written answers, and historical logs.

14. Test retrieval and the final answer separately

When an answer fails, check the retrieved sources before changing the prompt.

If the correct section never appeared, investigate the content, chunking, metadata, filters, or search configuration. If the correct source appeared but the answer was still wrong, look at the instructions, model, and answer-generation step. Measuring both stages prevents a prompt change from hiding a retrieval problem.

Run the evaluation set against a staging index whenever you change the corpus, chunking, retrieval settings, prompt, or model. Keep the previous results so you can see what improved and what regressed.

15. Start with a bounded pilot and classify every failure

You do not need perfect documentation before testing an assistant. You do need a clear scope. Start with one product, audience, or workflow where the sources are reviewed and users have another route to get help.

Log weak and unanswered responses, then classify the cause:

• The answer is not documented

• The source is outdated or contradictory

• The correct source was not retrieved

• The wrong product or version was selected

• The user did not have the right access

• The model misread good evidence

The first two clearly belong in the documentation roadmap. The others point to retrieval, scoping, access, or answer generation. Some failures will need changes in more than one place.

If you are unsure where to begin, run ten questions that your support team answers every week. Check the sources the assistant retrieved alongside the prose it generated. You will know what to fix next.

We built Biel.ai around this approach. Its content-gap analytics show what users are asking, which questions keep coming up, and where your documentation needs work.

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.

Some examples worked. Others did not compile. One called a method that no longer existed. Another used a dependency version from two releases earlier.

You could not tell from the page. The formatting was clean, the syntax highlighting worked, and each code block had an explanation. The failures appeared only when we ran the code.

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