How I redesigned our docs for agents

Sometimes the hardest part of rebuilding documentation is deciding what not to keep.

At SLNG, a lot changed over the summer, and we shipped a new platform in a few weeks. New features, new models, more regions, new ways to use the platform. The docs needed to catch up, not just by adding more pages, but by making sure developers could actually find what they were looking for.

The tool wasn't the problem. We were on Mintlify, with some automation already in place, and happy with it. The problem was how everything was organized around a product that kept moving.

So, working with our CPO, I led a redesign of the whole documentation experience.

Along the way we realized we weren't only writing for humans anymore. More than half of our docs traffic was coming from agents, and agents were also helping us write the docs. That changed a few decisions, and it's the thread running through this post.

1. Start with a mind map, not a migration plan

In 2026 you'd think this part would be easy. Throw your Notion specs and Linear tickets at your favorite coding agent and ask it to reorganize the docs.

We tried. The results weren't great.

The agent was too influenced by what we already had. Instead of rethinking the structure, it kept fitting the old pages into a new sidebar. Our existing content was holding it back, and honestly, it was holding us back too.

So we went back to the drawing board. Literally.

We opened a mind map, forgot about pages and navigation for a moment, and started from the people who visit the docs:

• A CTO or technical lead evaluating the product, who wants to understand the architecture, what it can do, and where its limits are.
• A developer implementing the API, who needs to get something working with clear steps and examples.
• An experienced developer coming back to check one endpoint, one parameter, or one error.

They don't have the same questions, and they won't navigate the same way. For each of them we asked: what do they need to understand first? What are they trying to accomplish? Which concepts are specific to our product and need explaining?

That mind map was our working document until we agreed on the structure. We settled on three main categories, which map almost one to one onto those three readers:

• Concepts: how the platform works, its components, the terminology.
• Guides: step-by-step instructions to accomplish a specific task.
• API reference: endpoints, parameters, schemas, everything you need when integrating.

Take regions. The concept explains what a region is and why it matters. The guide shows you how to use one. The API reference gives you the base URL. Same topic, three needs.

Only once we agreed on the structure did we open the editor and create the skeleton: sections, pages, navigation, no content. Then we went back to the old docs and decided, page by page, what to keep, rewrite, split, or remove.

If you're about to do this: map your documentation without looking at the existing sidebar. The best thing we did was stop looking at what we already had.

2. One task, multiple ways to get there

Once we had our structure, the next question was how to write the guides.

At SLNG, developers could accomplish many tasks through the Dashboard, the API, or the CLI. Different ways to get to the same result, depending on what you're comfortable with.

We could have written a separate guide for each, but that meant repeating the same explanations and keeping multiple tutorials up to date. Not ideal when the product changes every week.

So we decided to organize our guides around what people want to achieve, rather than how they choose to do it.

Luckily, Mintlify already had what we needed with its built-in Tabs component.

At each step, readers can pick their preferred path: Dashboard, API, or CLI when available. The prerequisites, explanations, and expected results stay the same.

For example, in the Create an Agent guide, you can follow the whole tutorial using either the Dashboard or the API, and switch between the two without leaving the page.

It also means we only have to explain a concept once. We introduce it, explain why it matters, and then show how to use it through each interface.

There is one catch: each path needs to make sense on its own. Someone following the API instructions shouldn't have to switch to the Dashboard tab to understand what to do next.

3. Keeping API references in sync with the product

One of the biggest challenges with API documentation is keeping it up to date. Your product evolves, new endpoints appear, parameters change, and suddenly your docs no longer reflect what your API actually supports.

At SLNG, we already had a separate repository containing our OpenAPI and WebSocket specifications. Rather than duplicating that information in the documentation, we wanted to reuse it and automate as much as possible.

We kept the responsibilities separate: the specifications define how the API works, while the documentation makes them accessible to developers.

There's another advantage to this approach. Those same specifications can be reused to generate SDKs, CLIs, or other developer tools. Your documentation shouldn't be the only consumer of your API definitions.

But separating things also introduces a new challenge: keeping everything in sync.

We added GitHub Actions to help with two common problems:

• API changes: When the backend introduces something new, like a model or endpoint, automated checks can flag missing specifications and create an issue or pull request.
• Specification updates: When a new version of the specs is published, the documentation repository gets notified that it needs to update its dependency.

By the time I wrapped up the project, we'd automated some of the most common checks and updates. There was still manual work involved, but we could catch certain changes before they went unnoticed.

The next improvement we need to work on is probably bringing the API specifications closer to the code itself. That way, backend changes could automatically trigger checks against the specs, rather than relying on separate updates.

4. Generate documentation from your product data

API specifications aren't the only things that can get out of sync with your product.

SLNG supports multiple speech models across different regions. Each model has its own characteristics, like latency, supported features, and availability.

And that information changes regularly. A new model gets added, another becomes available in a different region, or its configuration changes.

Keeping all of this updated manually would be a nightmare.

Luckily, the backend already had all this information. So why maintain it twice?

We wrote a few scripts to fetch model information directly from the backend and store it as JSON in the documentation repository.

From there, we generated the model catalog, including model details and regional availability. We could reuse the same data across pages and components instead of hardcoding it everywhere.

At the time, a GitHub Action ran three times a day to check for changes and create a pull request when something needed updating.

For example, if a model became available in a new region, the next sync could pick it up and propose the corresponding documentation update. No need to manually edit tables across multiple pages.

Of course, we shouldn't generate everything. Model availability and technical specifications are facts we can pull from the backend. Explaining what a model does, when to use it, or how to choose between models still requires some writing.

The idea was to automate frequently changing information, so we could spend more time on content that actually helps developers make decisions.

5. Making screenshots easier to maintain

We wanted our documentation to be more visual, especially for developers following guides through the Dashboard.

Screenshots are great for that. But there's one problem: they get outdated quickly, especially when your product changes every week.

A button moves, a menu gets renamed, or the whole interface changes. Suddenly, your screenshots no longer match what users see.

And who wants to manually retake dozens of screenshots every time the UI changes?

We found Heroshot, a tool that lets you automate screenshots using scripts.

We created a dedicated test account with sample organizations and configurations, then wrote scripts to navigate through the Dashboard, capture specific screens, and highlight the relevant sections.

Instead of manually going through the entire process, we could regenerate all our screenshots with a single command.

At the time, we still triggered the process manually. A possible next step was to connect it to the frontend repository, so that UI changes could trigger a screenshot refresh for review.

6. Going beyond Mintlify's built-in components

One thing I really like about Mintlify is the number of components available out of the box. Tabs, cards, callouts... There's already a lot you can do without writing custom code.

But for a few parts of our documentation, we wanted something more tailored to the product.

We ended up building three custom components:

• Regions map: Instead of listing all our regions in plain text, we created an interactive map using SLNG's branding, making it easier to visualize where the platform is available.
• Model cards: We wanted the model catalog to be more visual than a long table. Each model gets its own card with its logo and key information, making the catalog easier to browse.
• API region selector: Probably my favorite one, because it's a bit of a hack.

SLNG's API uses different base URLs depending on the region. Mintlify already provides a dropdown to select the base URL, but it's easy to miss when you're focused on an endpoint.

We wanted something more obvious. A big yellow box showing all the available regions with their flags, right where developers would see it.

The interesting part is that we didn't build a separate region selector. We wrote a small JavaScript hack that hooks into Mintlify's existing base-URL dropdown and lets our custom component control it.

Clicking on a region in the yellow box updates the base URL in the API reference accordingly.

And remember the model data we automated in the previous section? We reused that same generated data to populate the available regions. So when a region was added or removed, we didn't have to manually update another list.

It's a small hack, but I like it. We kept Mintlify's API reference functionality and added a more visual way to interact with it, without maintaining another list of regions.

The catch? These components rely on client-side JavaScript, which isn't necessarily available to every reader.

And that became particularly interesting when we looked at the documentation traffic.

7. Making documentation work for humans and agents

At the time, 55% of SLNG's documentation traffic was coming from agents, and that share was growing.

That's a pretty big audience to ignore.

We had spent time making the documentation more visual, with interactive maps, model cards, and custom components. Great for humans, but not necessarily for agents.

The problem is that many of these components rely on JavaScript running in the browser. Coding agents often consume documentation as Markdown or text, so they might not see any of that content.

We needed a way to offer both experiences without maintaining two separate versions of the documentation.

While browsing Mintlify's components, I stumbled upon Visibility. Exactly what we needed.

It lets you display different content depending on whether the reader is a human or an agent.

We used it on the homepage. Humans got the full visual experience, with illustrations, interactive components, and integrations. Agents got a simpler Markdown version, with a short explanation of the platform and direct links to the most useful resources.

And the nice part? Both experiences lived in the same index.mdx file.

Here's a simplified version of how it works:

<Visibility for="humans">
  {/* Visual homepage with interactive components */}
</Visibility>

<Visibility for="agents">
  # SLNG documentation

  - [Quickstart](/guides/get-started/quickstart)
  - [Models](/models/catalog/all-models)
  - [API reference](/api-reference/authentication)
</Visibility>

We didn't need to rebuild the documentation for agents. We just needed to make sure they could access the important information without relying on client-side JavaScript.

You can compare SLNG's homepage with its Markdown version to see the difference.

With more developers using coding agents to explore APIs and build integrations, I think this is something we need to consider much earlier when designing documentation.

Agent-first doesn't mean forgetting about humans. It means making sure both can find what they need.

Human view	What agent sees

8. Turning writing feedback into reusable instructions

Even with a better structure and more automation, we still had one challenge: writing good technical documentation.

It's harder than it looks. You need to know your audience, introduce concepts in the right order, explain jargon without overwhelming readers, and make sure someone can actually follow your instructions.

And just because an LLM can generate documentation doesn't mean the result is good. You often end up with something that sounds professional but is unnecessarily verbose, full of jargon, or missing important steps.

We noticed we were making the same corrections over and over during reviews. So why not turn those corrections into reusable instructions?

We added an AGENTS.md file to the documentation repository, with guidelines on terminology, structure, examples, and where to find reliable product information.

We also started using skills we found on skills.sh, alongside SLNG's own brand guidelines:

• technical-writer: Our quality checker. It helps ensure content follows a logical progression, explains unfamiliar concepts, includes prerequisites, and gives developers a way to verify their results.
• humanizer: Helps clean up LLM-generated text, removing filler, generic AI phrasing, and unnecessary complexity without changing the meaning.
• slng-brand: A skill we created to keep the writing aligned with SLNG's voice: direct, technical, and without unnecessary marketing language.

Our recommended review process combined these skills: brand voice, humanizing, technical structure, and one final brand check.

They're not magic, and they sometimes disagree. But they gave us a common baseline, whether someone was writing documentation manually or using a coding agent.

We also added separate automated checks to validate things like JSON and code examples. Writing skills helped with clarity and structure, while those checks caught technical errors.

We treated the guidelines as living documentation too. Whenever the same feedback came up across multiple PRs, we could update the instructions instead of explaining it again next time.

9. Looking back, what would I do differently?

Rebuilding SLNG's documentation taught me a few things, and not all of them were technical.

Take a step back before jumping into implementation. We spent too much time trying to reorganize existing content before asking ourselves what the documentation should actually look like. The mind map ended up being one of the most useful parts of the entire project.

Not everything needs to be solved with AI. Throwing Notion pages, Linear tickets, and old documentation at a coding agent won't magically give you a great information architecture. AI is great at helping you execute, but you still need to make the decisions about what belongs where and why.

Start thinking about agents as readers. With more than half of the documentation traffic coming from agents at the time, it was hard to ignore how people consume documentation today. I think we're moving toward agent-first documentation, but that doesn't mean forgetting about the humans using it.

There was still plenty to improve when I wrapped up my time at SLNG. Some automations were only partially implemented, the writing guidelines were still evolving, and the product certainly wasn't going to stop changing.

But that's also the point. Documentation isn't something you write once and forget about. It needs to evolve alongside your product.

And perhaps the biggest lesson for me is that good documentation isn't just about having the right information. It's about making it easy to find, understand, and use.

You can check out what we built at docs.slng.ai.