Knowledge Base Maintenance Without a Documentation Day

Friday, 15:50, at Redbrook Engineering. The documentation day is in the team calendar for the fourth time this year. The first one was moved for a go-live, and the second for a network outage. The third was moved because two of the four technicians were on leave in the same week. And this one, next Tuesday, has just been moved for quarter-end. The finance director has described quarter-end as "not negotiable" and the calendar has described the day as "rescheduled". Lena, who runs the desk, looks at the knowledge base instead. A hundred and forty articles. Sixty-one past their review date. Twelve about the project-management system, all showing the screens from before the spring upgrade. Across the room, Omar closes a ticket by pasting a link to one of those twelve and typing underneath it, "ignore step three, the button has moved". He has typed that sentence about thirty times since spring. It is faster than fixing step three, each time.

Maintenance of a knowledge base is keeping the articles that already exist right, findable and few. This article argues that it can only be done in minutes attached to work that already happens. It can never be done in a day set aside, because the day is never coming. Consider the ticket that uses an article, the change that alters a system, and the turn of the quarter. Add the moment an article stops being needed. Those four happen whether or not anyone plans them, and each is a place where a few minutes of upkeep fits. This article is part of our Knowledge Base Fundamentals series, and it is about the four moments.

It covers why the documentation day never comes, briefly, because another article owns that. Next come the four maintenance moments, in a table, and the ten-second check on reuse. We cover marking an article stale, and why an honest stale notice beats a quiet wrong one. Then come the quarterly sweep, retiring rather than hoarding, and the change that should trigger a review. We finish with a short war story and the quarterly sweep sheet to copy, in that order. Writing new articles during tickets is a separate subject. It belongs to the Capture Knowledge While Solving series. This article is about the articles you already have.

Why the Documentation Day Never Comes

The documentation day is never urgent, and a desk runs on urgency. So the day is moved by whatever is urgent that week, and something always is. That is the whole mechanism, and the reasons behind it, along with what to do instead for new knowledge, are set out in Why Documentation Day Never Comes. For existing articles the point is narrower. Even when the day does arrive, a day of rewriting from memory produces articles that nobody has tested against a real ticket. They are written by people who have spent eight hours doing something they do not usually do. Redbrook's one completed documentation day, two years earlier, had produced thirty-one articles. Nine were wrong on publication because the author was describing a screen from memory and the memory was of the previous version.

Maintenance has to attach to things that happen anyway, because those are the only things that reliably happen. A ticket that links an article happens forty times a week. A change to a system happens a few times a month, with a record. The quarter ends four times a year whether finance likes it or not. And an article stops being used at some point, which shows in the numbers. None of these can be moved for quarter-end, because none of them is an appointment. They are the work, and maintenance rides on the work, in minutes, or it does not happen at all.

The Four Maintenance Moments

There are four moments when an existing article gets looked at. The table below is the whole maintenance system: who looks, for how long, and what they do. Everything else in this article is detail on one row or another. Notice that the longest of the four is thirty minutes per person per quarter. The other three are measured in seconds or in a line on a form. A knowledge base of a few hundred articles can be kept right by a desk of four on about an hour a month each. That works as long as the hour is spent at these moments and not saved up for a day.

The four moments feed each other. Reuse catches the errors that matter most, because they are in the articles that get used. Change catches the errors before a reader does, because the owner is told that the screen is about to move. The quarter catches whatever the first two missed, and the articles nobody has used, which the first two will never see. And retirement is what keeps the other three small, because every article you archive is one fewer to check. A knowledge base that does the first three and never retires anything has a quarterly sweep that gets longer every quarter. Eventually it becomes, in effect, a documentation day, at which point it stops happening.

Review on Reuse: The Ten-Second Check

Every time a technician opens an article to use it or to link it, they read it as the reader will. That takes about ten seconds for a typical article and is the single most valuable maintenance habit a desk can have. The technician is about to send this article to someone who will follow it literally. They are the last person to see it before it is trusted. If the steps are right, nothing further happens, and the article has had its review for the day. If a step is wrong in a small way, the technician fixes it there and then. Examples are a renamed button, a moved menu, or a changed number. The fix takes two minutes, and the technician drops the owner a line. If the article is wrong in a large way, they put a stale notice at the top, send the requester the correct steps directly, and tell the owner. The one thing they do not do is send the link with a correction typed underneath it.

"Ignore step three" is the habit that kills knowledge bases slowly. It feels efficient, because typing one sentence is faster than editing an article, and the requester does get the right answer. But the article is still wrong for the next reader, who did not get the sentence. That could be the requester who finds it from the portal, or the new technician who links it without knowing. It could be the colleague who covers Omar's tickets when Omar is away. Each of them follows step three. And the correction lives in Omar's fingers, where it goes on leave when he does. Never say "ignore step three". Fix step three. If you genuinely cannot fix it in the moment, the stale notice is the correction that stays in the article rather than in the reply. It takes exactly as long as typing "ignore step three" did.

The ten-second check is about the article being right. Making it better is a related habit. That means adding the step everyone gets stuck on, the synonym readers search for, or the "what you will see" line that was missing. The habit has its own article, Refine on Reuse. The two habits sit well together: check that it is right every time, improve it when you have a minute. The maintenance habit is the first of those. An article that is right and plain beats an article that is rich and wrong, and the ten seconds are what keep it right. Some tools let a technician mark "used this, still correct" on an article, which gives the owner a trail of checks. Most do not, and the check still happened. The article is still right. That was the point.

Marking an Article Stale

A stale notice is one plain sentence at the very top of an article saying that part of it is out of date. It says what the reader should do in the meantime, who is fixing it, and the date. "Stale: the upload page moved in the spring upgrade and steps three to five are out of date; ask the desk for the current steps while this is updated. Owner: Lena. Dated the ninth." That is the whole notice. It is written in thirty seconds by whoever found the problem. The notice turns a wrong article, which misleads with confidence, into an honest one. Readers can still use the parts that are right and will not follow it into the parts that are not.

Honest stale beats quiet wrong because readers judge the whole knowledge base by the article in front of them. A reader who follows step three, fails, and raises a ticket has learned that the knowledge base lies, and will not open it next time. Consider a reader who sees "stale, steps three to five out of date, ask the desk". That reader has learned that the knowledge base is maintained by people who tell the truth. That reader will open it next time even though this article let them down. Articles do not age gracefully. They age in secret, and the notice is the article admitting its age out loud, which is the only dignified option available to it.

Stale is a status, and a status has a deadline. In the register, an article marked stale carries the date of the notice and the owner's name. The editor's weekly check lists every stale article with how long it has been stale. Two weeks is a reasonable limit. By then the owner has fixed it, or has said why not, or the editor fixes it themselves. Or the article is retired because nobody can say what the correct steps are, which is its own finding. What must not happen is the stale notice becoming permanent. That leaves the knowledge base dotted with articles that have been "being updated" since the spring before last. A stale notice is a promise with a date on it. Keep the date.

The Quarterly Sweep

The quarterly sweep is thirty minutes per owner, in the first week of each quarter. It covers the articles in the register whose review date has fallen due. And it is the only scheduled maintenance the knowledge base gets. Thirty minutes is the point. A thirty-minute appointment survives quarter-end, go-lives and leave in a way a day never does. Nobody moves a half-hour meeting for an outage; they attend it late. The editor sends each owner their list a few days before: the register sorted by review due, filtered to their name. That is usually eight to fifteen articles, at two or three minutes each.

For each article the owner asks three questions and records one outcome. Is this still how it is done? Has anyone used it since the last review? Is the title still the words a reader would type? The outcome is one of four words. "No change": the date is updated and that is all, and this will be the answer for most. "Fixed": a small correction was made during the review. "Stale": the article needs more than a few minutes, so it gets the notice and a deadline. "Retire": nobody has used it, or the thing it describes has gone, so it is archived with a note. The owner writes the outcome and the date against each article on the sweep sheet. They send the sheet to the editor by the end of the week.

The editor's part is to collect the sheets and read them for patterns, which takes another thirty minutes. Four articles stale from the same system means that system changed and nobody ran the change moment, which is a conversation with whoever runs changes. Six articles retired from one category means that category may be going the same way. Ten articles with "no change" and no use in a year is a retirement list for next quarter. And the sweep is also where the editor asks the slower question that reuse never asks. Is there an article nobody has opened since the last sweep, and does anyone still need it? The answer, by default, is no, and the register gets shorter, which is what makes next quarter's sweep thirty minutes as well.

Retiring Rather Than Hoarding

Retiring an article means archiving it out of the search results with a one-line note saying when and why. The reason to do it is that every unneeded article makes the needed ones harder to find and the whole collection harder to trust. A reader searching "expenses" who gets four results, two of them about a system that was switched off, learns to distrust all four. A sweep that covers two hundred articles when the desk uses sixty is a sweep that will be skipped. Hoarding feels safe and costs the knowledge base its two most important properties. Those are that search finds the right thing and that readers believe what it finds.

Retire, do not delete. The archived article keeps its history, its owner's name and its note. It can be restored in a minute if it turns out to be wanted, which happens occasionally and is not a reason to keep everything. The known-error articles already follow this pattern. When the permanent fix goes in, the record is marked fixed and archived with the cause attached. That way, if the symptom returns in two years the next technician has the history. Ordinary articles deserve the same. "Archived in the autumn: the expenses system this describes was replaced; see 'Submit an expense claim' for the current steps" is a note that costs ten seconds and saves someone an hour of wondering whether the old article was ever right.

Three triggers retire an article, and the sweep is where they are checked. The thing it describes has gone: a system switched off, a form withdrawn, a supplier changed. Nobody has opened it in a year and no ticket of its type has arrived: the question stopped being asked. Or a better article now answers the same question: merge, and archive the loser with a note pointing to the winner. The objection is always "someone might need it", and the answer is always the same. If they do, it is in the archive, restored in a minute, and they will need the current version anyway. Nobody has ever needed a wrong article. They needed the right one, and the wrong one was standing in front of it.

The Change That Should Trigger a Review

Most stale articles were made stale by a change that somebody planned, announced and carried out, with a record. And the articles were simply not on the record. The spring upgrade at Redbrook had a change record with a date, a back-out plan and a list of affected users. It did not have a list of affected articles, so twelve articles went stale on a Saturday morning. They stayed that way for six months while Omar typed "ignore step three". The fix is one line on the change record: "Knowledge base articles affected". It is filled in before the change by searching the knowledge base for the system's name and listing the hits. Five minutes. The owners are told, the articles are reviewed in the week after the change, and the screens in them match what the reader sees.

The change record is the right place for this because it already exists and is already read. The one-page record described in The One-Page Change Record has room for a line. The review that approves changes can ask "which articles?" in the same breath as "which users?". Changes that should trigger an article review are broader than upgrades. They include a new request form, a changed approver, a new supplier's support number, a moved office, or a renamed department. They also include a new phone model, a password policy change, and a leaver, who is a change to every article they owned. If the change touches anything a reader could be told to click, type or phone, it touches an article. In that case, the search for the system's name finds which.

Screenshots and videos go stale faster than words. A renamed button in the text is a one-word edit and a renamed button in a screenshot is a new screenshot. So the change moment matters most for the articles with pictures in them. Keeping those current is its own subject, in Keeping Media Current When Screens Change. And there is a quiet early-warning signal worth watching between changes. When an article starts sending readers wrong, the tickets that linked it start reopening, because the requester follows the steps, fails, and replies. If you run QuerySolv, a requester's reply reopens the resolved ticket and the reopen rate sits in the reports. So a stale article often shows up as a cluster of reopens on one ticket type before anyone reports the article itself. In any tool, three reopens in a week on tickets that all linked the same article is the article asking for a review.

A Short War Story: The Expenses Article at Kestrel Print

Kestrel Print was a commercial printer with two sites and a desk of three. It had an article called "Submit an expense claim" that was linked in about thirty replies a quarter. A supplier update moved the receipt upload button under a menu called "More". Dani, who handled most finance tickets, began adding "ignore step three, the upload button is now under More" to every reply that linked it. She did this because the article's owner had left and Dani was not sure she was allowed to edit it. This went on for four months without a single complaint, since every reader got the correction with the link. In the fifth month Dani took two weeks' leave. Her colleague Marek sent the link without the sentence to eleven staff in the week before month-end. Fourteen tickets reopened in four days as each of them failed at step three and replied. Finance closed the month two days late. The finance manager asked the desk, with some restraint, how an article could be wrong for four months when the desk had known from the first day. The article was fixed in ninety seconds when Marek finally opened it to see what step three said. A correction you say instead of make is a correction that leaves when you do, and it had left on a Friday with Dani's out-of-office.

The Quarterly Sweep Sheet

The sweep sheet below is one page per owner per quarter, plus a short summary for the editor. The owner fills in the top from the register sorted by review due and answers the three questions for each article. They record one of four outcomes and return the sheet within the week. The editor's block collects the counts, the stale list with deadlines, and the retirement list. It also collects the changes this quarter that should have triggered reviews, so that the pattern-reading has somewhere to land. It is deliberately short. A sweep sheet that takes longer than the sweep is a sweep sheet nobody fills in.

QUARTERLY KNOWLEDGE BASE SWEEP — ONE SHEET PER OWNER
Owner: ______________   Quarter: ________   Sheet due back by: ________
Articles due this quarter (from the register, sorted by review due): ____

FOR EACH ARTICLE (two to three minutes each)
 Article title                          Still how it's done?  Used since last review?  Title still the reader's words?  Outcome      Date
 ____________________________________   [ ] yes [ ] no        [ ] yes [ ] no           [ ] yes [ ] no                   __________   ______
 ____________________________________   [ ] yes [ ] no        [ ] yes [ ] no           [ ] yes [ ] no                   __________   ______
 ____________________________________   [ ] yes [ ] no        [ ] yes [ ] no           [ ] yes [ ] no                   __________   ______
 ____________________________________   [ ] yes [ ] no        [ ] yes [ ] no           [ ] yes [ ] no                   __________   ______
 Outcome is one of:  NO CHANGE (date updated)  /  FIXED (small correction made now)
                     STALE (notice at top; deadline two weeks)  /  RETIRE (archived with a note)

STALE NOTICE WORDING (paste at the top of the article)
  "Stale: ______________________ is out of date since ____________.
   In the meantime, ______________________. Owner: __________. Dated: ______."

EDITOR'S SUMMARY (collected from all sheets, thirty minutes)
  Articles swept: ____   No change: ____   Fixed: ____   Stale: ____   Retired: ____
  Stale list with deadlines:
    ____________________________   owner __________   fix by ________
    ____________________________   owner __________   fix by ________
  Retired this quarter (title, reason, pointer to replacement if any):
    ____________________________   ______________________________
  Unopened since last sweep, still needed?  ____ articles; asked the desk on ________
  Changes this quarter that touched articles:
    Change ______________________   articles affected ____   reviewed after?  [ ]
    Change ______________________   articles affected ____   reviewed after?  [ ]
  Patterns noticed (same system, same category, same owner): ______________________
  Reopens clustering on one article's tickets?  [ ] which: ______________________
  Next sweep: first week of ________   Invitations sent: [ ]

Lena cancelled the documentation day for good on the Friday. She put a thirty-minute sweep in the first week of the next quarter instead, with a sheet for each of the four owners. The first sweep found the twelve project-management articles. It fixed nine of them in the half hour because the fix was a renamed button. It marked three stale with a two-week deadline, and retired twenty-two articles nobody had opened in a year. The change record gained its one line the following month. Omar has not typed "ignore step three" since, because step three is right. The other reason is that the stale notice takes exactly as long to write and does not go on leave with him.

Frequently Asked Questions