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 you notice
Your documentation was right when you wrote it. Your product has changed ten times since. This page explains how documentation goes stale, why it happens faster the more often you ship, why nobody on your team spots it, and how you can still catch it in time. 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 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 was last year. Three options have been added since. Nothing in the article is wrong. It simply 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 does not go stale because your team is careless. It goes stale because writing and building happen at different moments, by different people, with different things on their mind.
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. Why that pattern is so hard to break, and how you get out of it anyway, is in How to fix stale 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.
That is not a discipline problem. It 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: attach the check to the moment of the change, keep every edit small, and let your customer questions decide what gets fixed first. That workflow is written out 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, not as a reminder.
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. It isn't.
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 question is not "who should review this?". The 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 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.
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 is an article that looks complete and is no longer right. You never find it by reading. You only find it by comparing.
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.
Curious how far your documentation has already fallen behind?
Create a free account or book a call and we will go through it together.
