Step 3: open the Orders tab and pick the order.
Step 4: click Save.
Step 5: the customer automatically receives a confirmation.
Home
Stale documentation
Stale documentation: why it happens and how to fix it
Your documentation was right when you wrote it. Your product has changed ten times since. This page is about the articles in your help center, the ones your customers read. Internal docs go out of date in exactly the same way. You'll see why it happens, why nobody on your team spots it, how to find stale articles and how to bring them back up to date. The product comes last.
Confirming an order
That button is now called "Confirm" and lives under a different tab.
What stale documentation is
Stale documentation, also called outdated documentation or stale docs, is any article that describes something other than what your customer sees on screen today. That sounds simple, but it comes in three kinds, and they look nothing alike.
The article that is wrong
Step four says "click Save", but that button is now called "Confirm" and lives under a different tab. The article still reads fine. It just no longer matches the product.
The article that is incomplete
It describes the settings page as it looked last year. Three options have been added since. What's there is still correct. It just says nothing about half the page.
The article that was never written
You built a feature, shipped it and announced it. Nobody wrote a word about it. To your customer that feels exactly like stale documentation: they search, find nothing, and send a question.
The word "stale" suggests there was once a fresh version. For the third kind there never was. It still belongs on this list, because the cause is the same: your product keeps moving and your documentation stays where it is.
Your documentation will go stale anyway
Documentation goes stale because writing and building happen at different moments, by different people, each with their own priorities. Even a careful team runs into it.
The developer who moves a button sees a small change. Fair enough. It is a small change. Too small to open the knowledge base, hunt for the article and fix one sentence. So they don't. And the support colleague who looks after the knowledge base has no idea the button moved. Nobody told her, because it was too small to mention.
Each of those changes is harmless on its own. The problem is what they add up to. Twenty small changes later, your article describes a product that no longer exists, and nobody can point to the release where it went wrong. There was no moment when the documentation broke. It just fell behind, quietly.
There is a second reason. Almost no software company has someone whose only job is documentation. It sits with a developer, a product manager or a support agent who does it on the side. When things get busy, and things are always busy, the side job is the first thing to drop. How you get out of that pattern is further down, under fixing outdated documentation.
The faster you ship, the faster it goes stale
A software company that ships every quarter has four moments a year where documentation can fall behind. A company that ships every week has fifty. The problem is the same in both cases. What changes is the pace, and the pace decides whether you can keep up at all.
4
moments a year where documentation can fall behind, at one release a quarter
50
moments a year at one release a week
+0
extra time to review it all: that stays the same
At four releases a year the classic approach still holds: someone goes through the knowledge base after each release. At fifty releases a year it falls apart. Nobody reads a hundred articles every week. So the review slips to "after the next sprint", then to "before the end of the quarter", and then to never.
This is simple maths. The amount of documentation grows with your product. The number of changes grows with your release pace. The time your team has to review it all stays the same. At some point those lines cross, and from then on your documentation is behind by default.
What does work at a high pace: tie the check to the moment of the change, keep every edit small, and let your customer questions decide what gets fixed first. The short version is under stopping your docs going out of date. The full workflow is in How to keep your docs in sync with a product that ships weekly.
Why nobody notices
You would expect a wrong article to stand out. Someone on your team reads it now and then, surely? They do, and they still miss it. The reason is a bit unsettling.
Your colleague, who knows the product
Someone who knows your product well does not read what is on the page. They read what ought to be on the page. When step four says "click Save", your colleague pictures the button that is there now and reads on. Her brain corrects the article for her, without asking. The better someone knows your product, the fewer errors they see in your documentation.
Your customer, who does not
Your customer has no such problem. They don't know your product, so they follow step four to the letter. They look for a button called "Save", can't find it, try again, and then send a question to your support team. Your customer is the only person who reads your documentation the way it was meant to be read: as instructions, one step at a time.
So your customer does see the error. They just don't report "article 27 is wrong". They ask a question. Your support team answers it, the customer moves on, and the article never gets fixed. The error sits there until the next customer trips over it.
What it costs you
Stale documentation never shows up on an invoice, so it feels free. You still pay for it, in three places.
1
Your support team
Start with your support team. Every question a correct article could have prevented now lands with a person. Not once, but every time, because the article stays wrong. Your team explains the same step ten times, in ten different emails, while the customer with a hard problem is still waiting in the queue. That is the time you lose, and you lose it again tomorrow.
2
Your customer
Then your customer. Someone who follows one wrong instruction does not open your knowledge base a second time. From then on they email you straight away. You built a knowledge base so customers could help themselves, and one wrong article teaches them to skip it. You do not win that trust back with a correction.
3
Your AI agent
And then there is something that did not exist a few years ago. More and more companies let an AI agent answer customer questions from their own documentation. As long as that documentation is right, this works well. If there is a wrong article in there, the agent gives that wrong answer with full confidence, to every customer who asks, faster than any colleague could. Stale documentation used to be an annoyance. Put an AI agent on top of it and it becomes a risk that grows every week.
Why your knowledge base keeps falling behind
If you are wondering why your knowledge base is always out of date, you have probably tried to fix it a few times already. A review calendar, an owner, a quarterly clean-up. And each time it petered out after a few months.
That is because all of those fixes start from the same idea: someone on your team goes looking for what is wrong. That is exactly the work nobody keeps up, for the reasons above. There is a lot of it, it is dull, and the person doing it does not see the errors anyway.
How do I get the errors to come to me, instead of going out to find them?
So the better question is: "how do I get the errors to come to me, instead of going out to find them?". How you set that up, and what you can really automate and what you can't, is in How do I keep my knowledge base up to date automatically?.
How you find stale documentation
The signals are already there. You only need to learn to read them.
1
A customer question about something you already documented
The strongest signal is a customer question about something you already documented. If the article exists and the customer asks anyway, something is off. Either they can't find it, or they don't understand it, or it no longer matches the product. In all three cases the question points you to exactly where to look.
2
A search with no results
The second signal is a search with no results. When customers search your knowledge base for a word that appears nowhere, they call the thing something different than you do, or the topic is missing altogether.
3
A colleague who would rather not send the link
The third signal comes from your own team. A colleague who would rather explain something to a customer in their own words than send a link to the article does not trust that article. Ask why. The answer is nearly always "it's not quite right any more".
4
The new hire
The fourth signal is the new hire. They read your documentation the way a customer does: literally, with no prior knowledge. The questions they ask in their first two weeks are a list of articles that have fallen behind.
Twenty questions, one hour of work
You can collect those signals by hand. Take your last twenty customer questions and, for each one, find the article that should have prevented it.
- Does it exist and is it right? Then it is hard to find or unclear.
- Does it exist but is it wrong? Then you have found stale documentation.
- Does it not exist at all? Then you have found a gap.
Twenty questions, one hour of work, and you know more about your documentation than after a week of reading. Why that works so well, and why documentation never goes stale all at once, is in Why your documentation can't keep up with your product.
How to fix outdated documentation
Once you've found them, you have a list of articles that have fallen behind. Work through it as a string of small corrections you can fit around other work. That's how the list actually gets shorter.
1
Start with what people read most
Fix the articles with the most visitors first, and the ones behind questions that keep coming back. A mistake in an article nobody opens can wait.
2
Flag it first, rewrite it later
Sometimes you can see an article is wrong before you know what it should say. Flag it straight away and note why. Whoever has the right information later knows exactly where to look.
3
Only change what's wrong
Cut what no longer applies and correct the step that's off. A short article that's right helps your customer more than a long one that's out of date. Then check every change in the live product, clicking through the steps the way a customer would. Your memory is probably a release or two behind.
4
Take dead articles away from your AI agent
If an article describes a feature that no longer exists, remove it from your AI agent's sources. As long as the agent can find the article, it will use it, even if it sits in an archive folder.
How to stop your documentation going out of date
Fixing clears up what's already wrong. To stop new errors piling up, bring writing and building closer together. The smaller the gap between a change and the article about it, the less can slip through.
Start with your release process. Add one line to every pull request or release checklist: "docs updated, or not needed". The person who made the change still knows exactly what changed. A week later, that memory has faded.
Give every important article one owner and a "last reviewed" date. This works best when the signals from your customer questions land with that owner, so the errors come to them.
Write your articles in small pieces: one task per article, one short section per step. When something changes, you edit one paragraph and leave the rest alone. And let your customer questions decide which article comes first.
How Sarrai finds it
For a small knowledge base, doing it by hand works. For a product that changes every week and gets questions every day, you want a system that makes the comparison for you. Plenty of tools hand you a report of low-scoring articles and unanswered questions. Working out what needs to change, and then writing it, is still left to you.
Sarrai answers customer questions from your own knowledge base. For every answer it records how confident it was. When it is not confident, the question goes to a colleague, who answers as usual.
Sarrai then compares that answer with the article it used itself. If the two differ, that article has fallen behind your product, and you get a proposal to update it. If no article existed, Sarrai proposes to create one, with the customer's question as the title and your colleague's answer as the content.
The most interesting case is the article Sarrai was confident about, while your colleague still answered something different. That article looks complete and is no longer right. You only find articles like that by comparing.
If you can't update an article yet, switch off "Available for AI Agent" on that article in Sarrai. The article stays where it is and the AI stops using it while you gather the right information.
All proposals land in one approval inbox. You see which conversation caused the proposal and what would change. You approve, edit or reject. The hunting is done. For software companies that ship weekly, that is the difference between documentation that falls behind and documentation that grows with the product.
Frequently asked questions about stale documentation
What is stale documentation?
Stale documentation is an article that describes something other than what your customer sees in your product today. It can be an article that's wrong, one that's incomplete, or one that was never written.
How often should you review your documentation?
Tie each review to a change in your product. A fixed schedule, say once a quarter, falls behind as soon as you release more than a few times a year.
How do you know an article is out of date?
The strongest signal is a customer question about something you've already documented. A search in your knowledge base that returns nothing is another, and so is a colleague who would rather explain something than send the link.
Why is stale documentation riskier with an AI agent?
An AI agent answers customer questions from your documentation. If an article is wrong, the agent gives that wrong answer with full confidence to every customer who asks. A colleague with doubts checks first. An AI agent has no idea the article is out of date.
What do you call a document you keep updating?
A living document. The text grows with the product, through a small update every time something changes.
Curious how far your documentation has already fallen behind?
Create a free account or book a call and we will go through it together.
