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.

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.

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.

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

The waitlist just opened: https://tally.so/r/RGxzzJ

Join for early access and help decide what features to build first.

What’s the most annoying part of your screenshot workflow? 👇

An AI chatbot lets them ask in plain language and get instant answers from your existing documentation.

Here’s how to add Biel.ai to your documentation. This guide uses Docusaurus, but Biel.ai works with any static site generator.

Disclaimer: I built Biel.ai. It’s a paid service with a free trial.

Prerequisites

• Docusaurus site (existing or new)

• Node.js v18 or higher

• A sitemap for your docs site

Step 1: Create a Biel.ai account

Go to app.biel.ai and sign up. Follow the on-screen instructions to create your account.

Step 2: Create your first chatbot project

1. In your Biel.ai dashboard, click on the Projects tab at the top.

2. Click Create project.

3. Enter your project details:

   • Project name: Choose a unique name.

   • Sources: Select Sitemap and enter the sitemap URL of your Docusaurus site (e.g., docs.domain.com/sitemap.xml).

4. Click Save.

You’ll receive a unique Project ID. Keep this handy, as you’ll need it later.

Step 3: Install the chatbot

1. Install the Docusaurus package:

npm install docusaurus-biel

2. Add Biel.ai to your docusaurus.config.js file:

plugins: [
    [
        ‘docusaurus-biel’,{
            project: ‘<PROJECT_ID>’,
            version: ‘latest’
        }
    ]
],

Replace <PROJECT_ID> with the Project ID you received earlier.

3. Run your site locally to ensure everything is working properly:

npm start

The chatbot appears as a floating widget. Users can ask questions and get answers from your docs:

Step 4 - Customize your chatbot (optional)

You can tweak the chatbot’s appearance and behavior in the docusaurus.config.js file. For example, you can change the button text or adjust the chatbot’s position:

plugins: [
    [
        ‘docusaurus-biel’,{
            enable: true,
            project: ‘<PROJECT_ID>’,
            bielButtonText: ‘ASK AI’,
            buttonPosition: ‘center-right’,
            modalPosition: ‘sidebar-right’,
            headerTitle: ‘Biel.ai chatbot’
            buttonStyle: ‘dark’,
        }
    ]
],

For advanced customization options, such as adding an initial message, suggested questions, or further editing the style, refer to Customization.

What the chatbot conversations tell you

The chatbot tracks what users ask, which reveals the gaps in your documentation. If 50 people ask about webhook authentication and you don’t have a guide, that’s a signal to write one. The questions show you what’s missing or unclear.

Also, keep in mind Biel.ai only works as well as the docs behind it. Well-structured, comprehensive docs lead to better answers. Gaps lead to poor ones.

It’s right there in the docs. But the user searched “automatic notifications” and got nothing. The docs call it webhooks. The user doesn’t.

Traditional search works when users know the right terms, and they usually don’t. They describe what they’re trying to do, not what the feature is called. Your docs could be perfect and users would still miss them because they searched the wrong word.

What we built

Over the past year, we’ve been building Biel.ai to solve this. It’s an AI chatbot that sits on your docs site and answers questions from your existing content. Think of it as ChatGPT, but answering only from your product documentation.

Users ask a question in plain language. Biel finds the answer in your docs and responds. No keyword matching, no browsing through a sidebar hoping to land on the right page.

What surprised us

Biel didn’t just help users find answers. It showed us what was missing.

The conversation logs revealed gaps we didn’t know about: topics we assumed were covered but weren’t, workflows that lived in Slack but never made it into the docs, basic things nobody had written down.

We went from guessing what users needed to seeing it in the data. The chatbot became a feedback tool as much as a support tool.

Who this is for

If you maintain documentation for a technical product and your users keep asking questions the docs already answer, Biel can help. It works with any static site generator, and setup takes about 10 minutes.

Want to see it on your docs? Send me a message at david@techdocs.studio with your docs URL and I’ll set up a demo.

But setting them up is painful.

You end up running parallel infrastructure just for previews. Most solutions need full GitHub org admin access, and security teams won’t approve it. Open-source projects get charged per user or per build minute. External contributors either can’t trigger previews or they rack up huge bills.

What I built

PushPreview is a GitHub Action. Drop /preview in a comment. Get a preview URL.

No infrastructure to maintain. No admin access needed. Private and public previews. Auto-cleanup when PRs close.

For open-source projects, pricing is fair. No per-user charges, no surprises from external contributors.

Join the waitlist

Sign up at pushpreview.com. Questions? david@techdocs.studio

You find out when the next person hits the same broken example. Or worse, you don’t find out at all.

I built PushFeedback to fix this.

What It does

It’s a feedback widget for documentation sites. Users click, highlight the problem, and submit. You get the feedback where you already work: GitHub issues, email, Trello, wherever.

No more “there’s a typo somewhere in the docs” messages. They show you exactly where.

Beta access

I’m looking for technical writers and docs teams to test PushFeedback and help shape what gets built next.

What you get: A free Starter license with unlimited feedback entries on one subdomain of your choice. You keep it after the beta ends.

How to join: Go to pushfeedback.com/beta and sign up. You’ll get a confirmation email with setup instructions. Adding the widget takes about five minutes, just a few lines of code, like Google Analytics.

What I need from you: use it, and tell me what works, what doesn't, and what's missing.

Beta spots are limited. Sign up: pushfeedback.com/beta

- David

Widdershins converts OpenAPI to Markdown. Here’s how to use it.

Prerequisites

• Have a valid OpenAPI document.

• Have Node.js installed on your computer.

• Have basic command-line knowledge.

What’s Widdershins?

Widdershins is the open-source command-line tool we’ll use to convert the OpenAPI document to MarkDown. By default, Widdershins outputs MarkDown compatible with renderers such as Slate, ReSlate, and Shins.

Thanks to its customizable template system, we can customize the output to make it compatible with other static site generators such as Sphinx, Docusaurus or Mkdocs.

Installing Widdershins

Widdershins can be installed with NPM. In the command prompt, run the following command:

npm install -g widdershins

After the installation has been completed, you can verify Widdershins installation by running widdershins --version in the command prompt.

Parsing OpenAPI to MarkDown

Once Widdershins is installed, run the following command in the console prompt:

widdershins openapi.yaml -o openapi.md

Replace openapi.yaml with the path to your OpenAPI file in YAML or JSON.

The command stores the resulting MarkDown file as openapi.md.

Customizing the output with flags

Widdershins comes with other built-in options to configure the output. For example, the option omitHeader removes the YAML front-matter in the generated Markdown file.

👉 Check out the complete list of available options in the official docs.

In this example, we’re running the command from the previous step with the new option omitHeader:

widdershins openapi.yaml -o openapi.md --omitHeader

Using custom-defined templates

Suppose you want to change the output’s format, but you can’t achieve the level of customization you are looking for by just tweaking Widdershins CLI’s options. In this case, what we did is override the template Widdershins uses with a custom-defined template.

Here’s how:

1. Create a new directory named .widdershins. Inside, create a second folder named templates.

mkdir -p .widdershins/templates
cd .widdershins/templates

2. Copy the contents from the file main.dot in the folder you just created.

curl https://raw.githubusercontent.com/Mermade/widdershins/master/templates/openapi3/main.dot > main.dot

3. Edit main.dot with your favorite code editor. The template engine Widdershins uses is doT.js. This enables you to access any variable from the OpenAPI description, even vendor extensions or nested fields.

From my experience, getting started with the template engine could be tricky. Here’s a cheatsheet with the delimiters I’ve been using more to render and iterate through variables:

Evaluate

{{ var enums = []; }} // Executes the JavaScript code between the curly braces.

Print

{{=a}} // Renders the contents of the variable a
{{=a.b}}  // Renders the contents of the nested variable a.b

Conditional

{{? a }} hello {{?}} // If a is true, prints “hello”.
{{? !a }} hello {{?}} // If a is false, prints “hello”.
{{? a || b }} hello {{?}} // If a or b is true, prints “hello”.
{{? a && b }} hello {{?}} // If a and b is true, prints “hello”.

Iteration

{{~ alist:a}} {{= a }} {{~}}  // Iterates throught alist and prints every element.

4. Run the Widdershins CLI. In this case, add the option -u with the path to .widdershins/templates:

widdershins openapi.yaml -o openapi.md -u ./widdershins/templates

Next steps

Once the conversion works, automate it. Add Widdershins to your CI/CD pipeline so the Markdown updates automatically whenever the OpenAPI spec changes.

For large API specs, the generated Markdown can get unwieldy. It’s worth post-processing the output to split it by endpoint or resource so the navigation stays manageable.

From there, configure your static site generator to render the generated Markdown with proper styling and navigation.

I write about documentation systems, developer experience, and technical writing. Get new posts by email

Formatting slides takes forever. Choosing fonts, backgrounds, spacing between elements. You spend more time fighting with PowerPoint than writing content.

Marp converts Markdown files into presentation slides. Write in plain text, add formatting with simple syntax, export to whatever format you need.

Here’s how to use it.

Creating the presentation

No matter which tool you use to create the presentation, the first step is to know what you want to explain. Once you have the topic, open a new file with the extension .md. Then, write your notes for your presentation in plain text using Markdown syntax.

New to Markdown? Here is a cheat sheet with the most common annotations you’ll need to format titles, links, and tables.

Split into slides

Once you have all the content outlined, split the slides with the annotation ---. Here is an example.

# Slide 1

* Item 1
* item 2
* Item 3

---

# Slide 2

## Subtitle

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Export to different formats

Marp is the framework we’ll use to turn Markdown into a beautiful slide deck. Unfortunately, the tool is not available as a web application, so you’ll need a bit of experience playing with the terminal to use the tool.

For example, try to run one of the following commands to convert a Markdown slide deck into HTML, PDF, or PTTX. Replace PITCHME.md with your file name.

# Convert slide deck into HTML
npx @marp-team/marp-cli PITCHME.md --html

# Convert slide deck into PDF
npx @marp-team/marp-cli PITCHME.md --pdf

# Convert slide deck into PowerPoint document (PPTX)
npx @marp-team/marp-cli PITCHME.md --pptx

Do you want to preview the slides while you edit the contents? To run Marp in watch mode, run the following command instead:

npx @marp-team/marp-cli -w PITCHME.md

Then, open the resulting HTML file with your preferred browser.

If you use Visual Studio Code, you can preview the resulting slides as you write them with the Marp Extension for VSCode.

Adding a theme

Let’s change the style of the presentation. You can use one of the built-in themes. At the top of the MarkDown file, define which theme you want to apply using the directive theme. The file header should look like this:

---
theme: default
---

I’ve decided to go with the theme gaia for my presentation. Moreover, Marp provides other configurable directives that simultaneously apply to all the slides.

For example, I defined default values for the font color, background image, and enabled pagination for my presentation.

---
theme: gaia
color: #000
colorSecondary: #333
backgroundColor: #fff
backgroundImage: url(’https://marp.app/assets/hero-background.jpg’)
paginate: true
---

Styling a single slide

In some situations, you’ll only want to enable a directive for a given slide. You can apply directives selectively with comments. The next code snippet shows how to disable pagination for the first slide.

<!-- _paginate: false -->

# Slide 1

* Item 1
* item 2
* Item 3
---

Another common directive used per slide is _class. Each theme may come with a set of predefined classes. For example, the theme gaia introduces the class lead. When used, this centers the slide contents.

As you can see, the first slide used the class centering the title, whereas the second slide didn’t, and the contents appear aligned on top.

If you’re a skilled CSS developer, you might want to create a custom theme from scratch. John Wadleigh explains how to do it in Custom themes with Marp.

Working with images

A picture speaks 1,000 words. Most presentations include images, and Marp extends Markdown to define their size.

Add an image to your slides and change the size with width and height options.

![w:32 h:32](image.jpg)

You can also apply filters to images, such as adding opacity, a shadow, or even rotating the image. Here you have all the available predefined CSS filters supported. For example, the following snippet shows how to convert a photo to grayscale mode.

![grayscale](image.jpg)

Marp also brings the option to use images as backgrounds. Backgrounds also accept the same filters as images and additional options to position them.

By default, all background images fit the slide, but you can use the option auto to preserve the original size.

# The image fits the slide
![bg](image.jpg)

# The image is not rescaled
![bg auto](image.jpg)

# The image is scaled in a percentual value
![bg 80%](image.jpg)

The options left or right position the background to the specified side.

Is Marp right for you?

Marp is a good fit when your slides are content-first: technical talks with code examples, text-heavy decks without complex layouts, anything you want under version control, or slides you need to export to several formats. Writing in Markdown is faster than fighting layout tools, and you get the whole docs-as-code workflow for free.

It’s the wrong tool when design is the point. Custom layouts, complex animations, and pixel-perfect visuals are all harder than they’d be in a drag-and-drop editor. And if your team isn’t comfortable with Markdown or the command line, the learning curve will cost you more than the tool saves.

The line is simple: if you spend more time on content than design, Marp saves you time. If you need pixel-perfect slides, stay with the visual tools.

In this article, we will break the Petstore example from the official OpenAPI documentation into smaller files.

A little side note before we start: This guide will be more helpful if you’ve documented an API project before by following the OpenAPI Specification. But don’t worry if you’re starting a new OpenAPI document from scratch. You’ll find a skeleton project ready to be adapted at the end of the post.

Prerequisites

This guide assumes that you’re familiar with the OpenAPI Specification 3.0 (previously known as Swagger). If you haven’t worked with the standard, I recommend you read first What is OpenAPI?. Then, try to write your first OpenAPI document.

Step 1: Reuse responses

It’s easier to start splitting an OpenAPI document if you’re already reusing schemas.

Say you have two endpoints: one listing all pets, another retrieving a single pet. Both return a Pet object.

paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      tags:
        - pets
      parameters:
        - name: limit
          in: query
          description: How many items to return at one time (max 100)
          required: false
          schema:
            type: integer
            format: int32
      responses:
        ‘200’:
          description: A paged array of pets
          [...]
          content:
            application/json:    
              schema:
                  type: object
                  required:
                    - id
                    - name
                  properties:
                    id:
                      type: integer
                      format: int64
                    name:
                      type: string
                    tag:
                      type: string
  /pets/{petId}:
    get:
      summary: Info for a specific pet
      operationId: showPetById
      parameters:
        - name: petId
          in: path
          required: true
          description: The id of the pet to retrieve
          schema:
            type: string
      responses:
        ‘200’:
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                  type: object
                  required:
                    - id
                    - name
                  properties:
                    id:
                      type: integer
                      format: int64
                    name:
                      type: string
                    tag:
                      type: string

Don’t define it twice. Following this example, define the schema once under components/schemas and reference it with $ref:

paths:
  /pets/{petId}:
    get:
      summary: Info for a specific pet
      operationId: showPetById
      parameters:
        - name: petId
          in: path
          required: true
          description: The id of the pet to retrieve
          schema:
            type: string
      responses:
        ‘200’:
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: “#/components/schemas/Pet”
components:
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string

Step 2: Reuse parameters

Now that you’re comfortable reusing schemas in the same file, let’s reuse the parameter petId from the operation showPetById.

As in the previous step, move the parameter from the path to the components/parameters section and use $ref to reference the component.

Here is an example:

paths:
  /pets/{petId}:
    get:
      summary: Info for a specific pet
      operationId: showPetById
      parameters:
        - $ref: ‘#/components/parameters/petId’
[...]
components:
  parameters:
    petId:
        name: petId
        in: path
        required: true
        description: The id of the pet to retrieve
        schema:
            type: string

Step 3: Import from separate file

By reusing definitions, your file should now be shorter, even before starting to split it. If you’re already pleased with the file organization, you can stop reading now... You’re still with me? Then let’s make our file more modular!

Do you remember the keyword we’ve been using to reuse content? $ref not only allows us to import objects from the same file but from other sources like a separate file or a remote URL as well.

Create a new file named schemas/Pet.yaml for the Pet schema. Then, move the definition to the new file. Here’s what the resulting file should look like:

// schemas/Pet.yaml
type: object
required:
- id
- name
properties:
id:
  type: integer
  format: int64
name:
  type: string
tag:
  type: string

Now, point $ref to the new file’s location.

// openapi.yaml
$ref: “./schemas/Pet.yaml”

Finally, do the same for the other objects that you might want to split into separate files.

Step 4: Move resources to a separate file

Until now, you’ve seen how to organize response objects and parameters. However, if the document defines several endpoints, you’ll likely still have a large file that’s difficult to maintain. Next, we’ll organize the resource paths into multiple files.

For example, you could create the file path/pet.yaml. This file should define all the available operations, with their associated parameters and responses for the endpoint /pets/{petId}:

//paths/pets.yaml
get:
  summary: Info for a specific pet
  operationId: showPetById
  tags:
    - pets
  parameters:
    - $ref: “../parameters/path/petId.yaml”
  responses:
    ‘200’:
      description: Expected response to a valid request
      content:
        application/json:
          schema:
            $ref: “../schemas/Pet.yaml”
    default:
      $ref: “../responses/UnexpectedError.yaml”

Then, import each path definition from the main OpenAPI document as we have been doing with the schemas and parameters.

//openapi.yaml
...
paths:
  /pets/{petId}:
      $ref: “./paths/pet.yaml

Finally, repeat the process for every other resource you want to import from a separate file.

Step 5: Organize with index files

Let’s go one step further! We can split up the project even more to achieve better organization. Our goal is to end up with a main OpenAPI document as tiny as the following one:

// openapi.yaml
openapi: “3.0.0”
info:
  version: 1.0.0
  title: Swagger Petstore
  description: Multi-file boilerplate for OpenAPI Specification.
  license:
    name: MIT
servers:
  - url: http://petstore.swagger.io/v1
paths:
  /pets:
    $ref: “./paths/pets.yaml”
  /pets/{petId}:
    $ref: “./paths/pet.yaml”
components:
  parameters:
    $ref: “./parameters/_index.yaml”
  schemas:
    $ref: “./schemas/_index.yaml”
  responses:
    $ref: “./responses/_index.yaml”

To achieve this, create the following _index.yaml files:

• parameters/_index.yaml

• schemas/_index.yaml

• responses/_index.yaml

Then, move to every file its definitions. For instance, ./schemas/_index.yaml for the Petstore example would look like:

Pet:
  $ref: “./Pet.yaml”
Pets:
  $ref: “./Pets.yaml”
Error:
  $ref: “./Error.yaml”

Step 6: Bundle back to one file

Some of the OpenAPI based tools support only a single file as an input. To continue using the spec with those tools, we’ll compile all the different files we’ve created with the command-line tool swagger-cli.

1. Open a new terminal. Then, install the package swagger-cli globally:

npm install -g swagger-cli

2. Run the command to merge all the files into one:

swagger-cli bundle openapi.yaml --outfile _build/openapi.yaml --type yaml

3. If everything goes well, you should see a single OpenAPI file compiled under the _build directory.

Putting it all together

Splitting a large OpenAPI spec into multiple files makes it more maintainable. In my experience, it also makes other developers more willing to contribute. When the project is well organized, proposing changes feels less intimidating.

Here’s the repository with the Petstore example divided into multiple files: openapi-boilerplate. Feel free to reuse it as a starting point.

I write about documentation systems, developer experience, and technical writing. Get new posts by email