Why your documentation can't keep up with your product

You have an article about your settings page. You wrote it three releases ago, and it still reads well. But the button in step four has a different name now, and it sits under a different tab. Nobody changed the article. Nobody noticed either.

That is documentation drift: your documentation falls behind your product. It did not become wrong on one day. It stayed behind, one release at a time.

Your documentation never goes out of date all at once

Outdated documentation sounds like something that happens to you. As if there was one release after which everything was wrong. It rarely works that way.

Every release moves something. A button moves. A field gets a new name. A step disappears because the system now does it for you. Each change is too small to open the documentation for, so nobody does. Ten releases later, your article describes a product that no longer exists, and you still cannot point to the release where it went wrong.

That is why keeping up is so hard with a product that changes fast. The problem is never in one release. It is in the sum.

Reading page by page does not work

The classic fix: someone reads all the documentation. Every quarter, article by article, with the latest version of the product open next to it.

Nobody keeps that up. With a hundred articles you are busy for days, and most of that time you read articles that are still correct. The one article that is really wrong sits somewhere between the ninety others. After two quarters, the review moves to next month, and then to never.

There is a second problem, and it is bigger. The person who reads your documentation knows your product. They read what should be there, not what is there. The moved button in step four? Their brain fills it in. The better you know your product, the less you see what is wrong in your docs.

Your customer does not know your product. They follow step four literally, look for the button, cannot find it, and send a question. So your customer reads your docs with the right mindset. They just do not tell you the article is wrong. They send a support question.

Let your customer questions do the work

That is where the solution is. Every support question about something you already documented is a signal that the article has fallen behind. Either nobody can find it, or it is unclear, or it is wrong. In all three cases, the question tells you exactly where to look.

So you do not need to read a hundred articles. You need to put your customer questions next to your documentation. Where a question comes in and the answer already exists, something is wrong with that article. Where a question comes in and no article exists, you have a gap.

You can do that by hand, and for a small knowledge base that is a good start. But once you ship every week and get questions every day, you want a system that makes that comparison for you. A system that puts your customer questions against your documentation and points out the gaps and the errors, so all you do is decide what changes.

How this works in Sarrai

Sarrai answers customer questions from your knowledge base. For every answer, it records how confident it was. When it is unsure, the question goes to a team member, 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 team member still answered something different. That is an article that looks complete and is no longer correct. You never find it by reading. You find it by comparing.

All proposals land in one approval inbox. You see which conversation caused it and what would change. You approve, edit or reject. The searching is done.

Why documentation goes stale in the first place, and what to do when it has been going on for a while, is in How to fix stale documentation. How to turn the signals in your customer questions into a routine is in How do you keep your knowledge base up to date automatically?. For software companies that ship weekly, this is the normal state of things.

What you can do on Monday

Take your last twenty support questions. For each one, find the article that should have prevented it. Does it exist and is it correct? Then nobody can find it, or it is unclear. Does it exist but is it no longer correct? Then you found drift. Does it not exist? Then you found a gap.

Twenty questions, one hour of work, and you know more about your documentation than after a week of reading.