Writing Knowledge Base Articles for Humans and AI
TLDR
Your help center now has two readers and one of them can't see the screenshot. AI retrieves fragments, not pages, so headings, callout boxes and images don't survive chunking. This covers what an AI knowledge base actually reads, how to write articles that stand alone, where visuals still earn their place, product boundaries, and why stale content is worse than missing content.
This article was first written on swifteq.com
Your help center used to be just documentation and a place for customers and support agents to find answers. Now, it's the thing your support bot reads to answer customers, and it never stopped being documentation.
This means every article now has two readers at once. The only problem is that one of them can't see the screenshot.
AI is confident, which can be good, but also not, as sometimes it can be confident to the point of being overconfident.
Let's say, the bot answers a customer confidently, the answer is wrong, you trace it back, and to a human the article is fine.
The human reading that same article would have gotten the result they were looking for because they had the screenshot, the layout, and the callout box sitting right next to the text. The bot had none of that, or at least had difficulty accessing it.
If You're Simply Missing an Article, the Bot Fails. A Stale or Thin Article Is Worse.
It produces an answer that sounds right and isn't, and that actually costs more to recover from than having no AI at all.
I've seen well-structured documentation raise AI resolution rates by about 15 to 25 percent, but on the other hand, thin or stale content produces confident wrong answers.
To fix this, focus on knowledge quality. It's the single biggest thing you can do to improve an AI knowledge base. And it doesn't necessarily matter which model you're using; it's your data that matters.
Depending on who you ask, or what LinkedIn post you're looking at on any given day, the honest range for how many tickets an AI agent resolves is somewhere around 40 to 70 percent. Again, the models are all very similar; it's the help center that is the differentiator.
But making it "AI-friendly" doesn't mean stripping your help center down to plain text or Markdown files. Don't forget that your customers still need to read it.
It's about writing so the important answers survive after the human-friendly context around them disappears. To make it "AI-friendly", you will have to determine these four things:
- What belongs in text.
- Where visuals still earn their place.
- How you separate products.
- How you handle content going stale.
Do that, start with pulling your most-cited articles, turn the images off, and read what's left. Can you make sense of it? Because if you can't, then AI probably can't either.
What an AI Knowledge Base Actually Reads?
The bot never reads your page in full. It retrieves fragments, or a handful of text passages, and builds an answer from those.
That's retrieval-augmented generation, or RAG. Instead of reading an article from start to finish the way a person does, it retrieves the passages it thinks are most relevant to the question and builds an answer from them.
So picture a nicely formatted article that a human reads from start to finish, and it flows perfectly well. For AI, that same article gets split into chunks: the heading, then paragraph A, B, and C.
The retriever hands back paragraph B on its own. The H1 above it, the paragraph before it, and the warning box two sections up are all gone.
This is a documented failure, not a bug. Each chunk gets stored as an isolated piece, disconnected from the document it came from. That's exactly why a retriever can hand back the wrong passage with full confidence.
The classic version is that it pulls step six without steps one through five. The model then invents the missing steps, or simply omits them, and that leads to the wrong or incomplete answer.
Everything that tells a human what matters here is visual, and none of it survives the chunk. Headings, spacing, bold text, callout boxes, and the red warning banner all help a person reading the page. A plain-text chunk keeps very little of that context.
Images give the retriever alt text and nothing else. On top of that, most alt text is just the filename. Even a 40-second GIF with no transcript gives it nothing at all.
Tables also have their own trap. The meaning lives in the header row, so a single row pulled back without its header becomes an ambiguous fact.
"Click the button shown below" means nothing once the image is gone.
Here's another quick way to test read something as an AI would; first, export one article, strip the images out, and then read a single chunk against the way a customer would actually ask the question, not the article title.
If that chunk doesn't answer the question on its own, the bot can't either. To take this further, build a 'Most Cited (30d)' view first so you're testing the articles the bot leans on most.
How to Write Knowledge Base Articles That Stand on Their Own
Knowledge base best practices have changed over the years.
Now, to help AI understand the purpose of your documentation, aim for one article that answers one question.
There should be no dependency on anything the reader may have seen first.
This means that the rule of thumb is basically: self-containment. What breaks a chunk the moment it's lifted out, is any reference pointing somewhere else, such as "as covered in the previous article," "see above," or "as mentioned."
Title the article as the exact question a customer would type, and put the direct answer in the first two sentences. Don't leave it implied by the heading or buried three paragraphs down. It needs to be in the body, early on, where the retriever will actually find it.
State prerequisites in the article itself. Don't assume them from the category the article sits in because the category is navigation for humans, and the chunk doesn't carry it.
Repeat the product name instead of leaning on "it," "the tool," or "the software." This matters more for a retriever than it does for a human because the person reading the page has the title for context. The chunk just has "it," or whatever generic name you're using.
Make sure you restate any warning or callout in the sentence it applies to. The colored box around it doesn't survive chunking, so if the caution only lives in the box, it's gone.
Keep it to one procedure per article. Anything with an "if you're on plan X" branch should be split into its own article.
The best way to handle all of this, and the template that ties all of this together starts with an answer-first opening block, followed by a one-line prerequisites statement, then a single procedure per page, with the product and plan named in the first paragraph.
Try this with the next article you touch and rewrite it so it survives being read as one isolated paragraph.
Screenshots, GIFs, and Video Still Belong Here
Screenshots, GIFs, and video are all supporting characters. They confirm the step, but they should never carry the step themselves.
The working rule is that every procedure has to be readable with the images, GIFs, and videos turned off.
This is not the same as stripping the visuals out.
Someone is still reading them, the human, and they should stay for the human. The point is that the text has to hold the full instruction on its own, with the image confirming it rather than being the only place the instruction exists.
This also helps humans who learn in different ways. Some people learn visually, some prefer reading, and others benefit from video. The visuals still have an important role. They just shouldn't be the only place where the instruction lives.
For AI, you have to spell the path out in text. For example: Settings > Billing > Payment Methods > Update Card, then put the screenshot or GIF underneath showing that exact same path.
GIFs still earn their place on anything spatial, drag-and-drop, multi-window workflows, or any process you can't cleanly write as a navigation path.
Video can stay too, but make sure you include a transcript or a short text summary underneath it. That block is what the retriever reads.
Write alt text as a sentence describing the screen and its state, not something like "Screenshot-Final-2.png." A better version would be, "Billing page with the Update Card button highlighted."
Fix the image-only steps first. It's one of the easiest wins because it immediately gives your AI more context that it can retrieve correctly.
Product Boundaries and Answers Crossing the Wrong Wire
The moment one help center covers more than one product, edition, region, or version, retrieval will blend them. Every blended answer looks correct and confident, but it isn't.
Imagine setup instructions are handed to an onboarding customer. Everything in the answer is true, but it's for the wrong product or version, which means none of it is actually usable.
That's worse than an obviously wrong answer because it's the right answer to the wrong question, product, or edition, and nothing about it looks off.
This happens because the retriever selects chunks from the wrong source document because they share surface similarities with the query, and it gets worse the more structurally similar your articles are. Two products with nearly identical setup documentation are exactly that case.
For humans, categorization separates your products while they're browsing the help center. It does not separate them for the retriever unless it's wired as a filter at query time.
So the product, edition, and version belong in the body, in the first paragraph, not just the title or breadcrumb.
Then watch your ticket data. If you're using AI, or even humans, to generate knowledge from tickets, a misrouted ticket can misinform anything generated from it.
It could arrive in the wrong bucket, and then an agent moves it to the right team, but the wrong product context is already attached. Let's look at a few more retrieval issues and solutions:
| Boundary | How it fails retrieval | How to scope it |
|---|---|---|
| Multiple products, one help center | Nearest-match across product lines, right verb wrong product | Product filter at query time, no shared generic titles |
| Editions and plans | Feature explained to a customer whose plan doesn't include it | Plan stated in the body, separate article per branch |
| Regions | Residency, billing or availability steps wrong for where the customer sits | Region named in body, regional variants split not conditional |
| Supported versions | Deprecated instructions rank alongside current ones | Archive old versions out of the retrieval scope, don't just unlink them |
The mechanic underneath all four rows is the same. Name the product and version in the first line of the body copy, and use query-time retrieval filters per product line wherever the tooling supports them.
To solve this across your knowledge base, identify the boundaries you actually have, then decide for each one whether it needs its own retrieval scope or simply stricter labeling inside the article.
AI Is Better at Updating Articles Than Writing Them
Point the tooling at the library you already have, not at the gaps within it. This means that AI can update existing articles quite well. A UI refresh, a terminology cleanup, and a quick human review, and it's done.
But, drafting brand-new articles from ticket data is where it falls short. Support professionals report that the success rates are low enough that reviewing the output often costs more than writing the article yourself.
The reason being is that AI is strong at pattern recognition. Updating is pattern matching against something that's already been decided is where it can work well.
But writing from scratch is deciding, which is not an area the AI excels at (without intense human oversight).
It's the same thing we see when prompting Claude or ChatGPT. The more refined your prompt is, the more supporting context and documentation you provide, and the stronger your Markdown files are, the better the output becomes.
If you rely on a one-shot prompt, it's the same as asking AI to write a knowledge base article from scratch. The output usually isn't what you're looking for.
Writing a new article means deciding things the model can't. Whether the article should exist at all, what's officially supported versus just tolerated, which exceptions matter enough to document, and where the product boundary sits.
Ticket data is full of workarounds and one-off exceptions presented as facts. The model can't tell which of those represents company policy and which is simply a customer improvising, or a support agent doing their best to help someone in the moment.
That's the judgment the job requires, and it's the part AI can't make.
PR-triggered or Jira-triggered drafts are useful, but as a stub and a reminder that documentation is owed, not as publishable copy.
If you do use AI to write your articles, set a draft-to-publish gate with a named approver for each category. The tooling drafts the stub, a human decides what the supported answer actually is, and nothing gets published without that review.
Think of it this way.
More and more developers are using AI during code reviews, but hopefully nobody is shipping code straight to production without a human reviewing and approving it first.
A knowledge base should work the same way. AI can help produce the draft and speed up the review, but it still needs human sign-off.
To test this yourself, run the tooling across your existing library first, and measure the review time before you let it anywhere near creating new articles.
Stale Content Is Worse Than Missing Content
A gap within an article makes a bot provide inaccurate answers because it can't identify that information is missing or recognize the gap in what it knows. A stale article makes it confidently wrong, and the customer acts on it.
Remember that missing information creates visible failures, but content drift is invisible until someone follows the old steps and they no longer work.
The stale article is the one that generates angry tickets. A missing article entirely usually just deflects to a human. Do note that this isn't to say you should simply remove articles. It's to say you should rewrite them properly.
Everything changed when support bots started citing their sources, and most do now. The article the bot answered from is shown to the customer, which means a stale article isn't just internal reference material anymore. It's customer-facing.
Your most-cited articles are the ones customers are most likely to see, so they should get the fastest review.
To make sure you don't fall behind stale content, set audit triggers based on change, not just on a calendar. A UI change, pricing change, plan change, deprecation, or anything shipped that changes a screen should trigger a review.
Watch the reopen rate on AI-answered tickets as one of your health metrics.
If AI-resolved customers come back within 48 to 72 hours more often than customers whose tickets were resolved by a human, your resolution number is probably inflated because those tickets weren't actually resolved.
Make sure you also archive stale content rather than leaving it published. An archived article can't be retrieved and served to anyone.
To begin, sort your review queue by citation frequency first, last-updated date second, and work from the top down.
Someone Has to Own This Now
Just like code reviews, coding, and software development, the help center has turned into a production system. Unfortunately, nobody's job description has changed to match.
Teams with a bot live today, or going live in the next two quarters, are the ones that need to define this new role. The knowledge base is infrastructure whether anyone is treating it that way or not.
This is less urgent for teams running a bot that's scoped to a short list of well-documented questions, with everything else escalating to a human.
Here's the reframe to keep in mind. The AI agent didn't add a new audience to write for. It exposed weaknesses that were already in the library.
Before the bot, customers who hit those weaknesses often gave up quietly or went shopping for another vendor. Now the bot hits those same weaknesses out loud, at scale, with the source article attached, and can frustrate far more customers.
The first move is simple. Pull your ten most-cited articles, turn the images off, read them cold, and fix what doesn't survive.
The ongoing cost isn't another tool. It's a named person's time on an audit cadence. That's because fixing AI isn't something AI can do.
Name a knowledge owner for each category, put the review cadence, or the audit triggers, on their calendar, and treat the citation-sorted review queue as their standing backlog.
Support work is already shifting from clearing the queue toward managing the knowledge behind it. So ask yourself this: "Is this someone's actual job on your team yet? If it isn't, whose job is it going to be?"
Because it can't be AI's job.