Keeping the Pair in Sync: One Truth, Two Documents

Monday, 08:50, at Meridian Parts. Hamid opens the queue to fourteen tickets from the weekend, and nine of them are the same ticket. "The article says the drawings folder is on drive S. There is no drive S." There has been no drive S since the spring, when the drawings share moved to a new server and became drive P. The runbook was updated the afternoon of the move, by the technician who did the move, because she had it open at the time. The user guide, "Finding the shared drawings folder", was not. It was a different article, in a different place, written by a different person the year before. Nobody at the desk knew the two were about the same thing. For five months, every user who did what the posters asked and searched before raising a ticket was told to look for a drive. That drive did not exist. Each of the nine tickets will be closed this morning with "use drive P". None of them will fix the article, because closing a ticket is a ticket and fixing the article is nobody's.

A runbook and the user guide derived from it are a pair: two documents describing one procedure for two readers. And keeping the pair in sync means that a change to the procedure reaches both documents, every time. It does not rely on anyone remembering that the other one exists. Pairs drift the moment one is edited alone. They are edited alone whenever the person making the change knows about one document and not the other, which is most of the time. This article is part of our Technician Docs vs User Docs series. This article is about the mechanism that stops the drift: one source of truth, a link in both directions, and a list of changes that trigger a review. It also covers a review that reads both, and a register that knows every pair.

It covers why pairs drift, the runbook as the single source of truth, and linking the pair so each knows the other exists. Next come the changes that must trigger a review of both, the review itself, and the signals in the queue that say a pair has already drifted. Who owns the pair, a short war story, and the sync register to copy come last, in that order.

Why Pairs Drift

Pairs drift because a change is made by a person, and a person knows about the document they have open. The technician who moves a share updates the runbook, because the runbook is what she was following. She does not update the guide, because the guide is a thing users read and she has not read it since it was published. The editor who tidies the guide after a user complains does not touch the runbook, because the runbook is technical and not theirs to touch. Each of them did the right thing to the document in front of them. The pair drifted anyway, because nothing in front of either of them said there was a second document.

Drift is also invisible from inside. A stale runbook is found by a technician at 02:10 who discovers a step is wrong, and that technician usually fixes it. So runbook drift is self-correcting, slowly and at night. A stale guide is found by users, who do not fix it. They raise a ticket, or they stop trusting the portal, and neither of those reaches the guide. The desk sees the tickets, closes them one at a time with the right answer, and never adds them up. Nine tickets saying the same wrong thing about the same article is a single fact about the article. Seen as nine tickets, it is nine small jobs, and small jobs do not get root causes.

The last cause is that nobody owns "both". The runbook has an owner, the guide has an owner, and when they are the same person they are still two tasks on two lists. When they are different people, the runbook's owner assumes the guide's owner will notice, and the guide's owner is waiting to be told. The gap between two owners who each assume the other has it is the same gap that tickets fall into between two technicians. It is closed the same way: a name on the pair, not on the halves.

One Source of Truth

The runbook is the source of truth for the procedure: the one document whose steps are tested and whose last-run line says when. Every other description of the procedure is derived from it. The guide's steps are never edited on their own authority. If a guide step is wrong, the question is whether the runbook step it came from is wrong. In that case, the fix is made in the runbook and then carried to the guide. If the runbook step is right and the guide step is still wrong, the derivation was wrong, and the guide is re-derived from the runbook. In neither case does anyone type a new step into the guide because it seemed right.

This rule feels bureaucratic for about a week and then saves the desk every month afterwards. It means that there is exactly one place where the procedure can be wrong. And the people most likely to find it wrong, the technicians, are the people who open that place. It means the guide can be rewritten from the runbook at any time by anyone. The mapping from runbook steps to guide steps was recorded when the guide was derived, as described in Writing the User Guide From the Runbook. And it means that "is the guide right?" is a question with a mechanical answer. Open the runbook, open the mapping, and read the guide against them.

Wording in the guide is a different matter from steps, and the rule should say so. Anyone can improve how a guide step is phrased, add a "what you will see" line, or fix a typo, without touching the runbook. None of that changes the procedure. What nobody can do is add a step, remove a step, reorder steps or change what a step does. Those change the procedure, and the procedure lives in one place. The line is simple to state and worth stating on the guide itself, in the agents-only note at the top. It reads: "Steps derived from RB-14. Edit wording freely; change steps only by changing RB-14 first."

Linked Pairs

Each half of the pair must know the other exists, which means an identifier on each and a reference in each to the other. The runbook carries its own number and the guide's: "RB-14, paired guide G-14". The guide carries its own number, and in the agents-only note that users do not see, the runbook's. The numbers are boring and that is the point. "The drawings folder article" is a description that two people will apply to two different articles; "G-14" is a name that applies to one.

The visible link runs one way. The runbook, visible to agents only, links to the published guide. That way, a technician reading the runbook can see what the user has already been told to try. The published guide does not link to the runbook. A link from a public page to an agents-only page is an invitation to ask what is behind the door. The answer is a document full of server names. The guide's reference to its runbook sits in the agents-only notes, in the register, or in the article's internal fields. It goes wherever the tool keeps text that users cannot see. Where the tool has no such place, the reference lives in the register alone, and the register becomes the thing that must be opened before any edit.

Linking also catches the pairs that were never pairs. When the register is first built, the exercise lists every runbook and asks "is there a guide for this?" It lists every guide and asks "which runbook is this derived from?" That finds the guides that were written from memory, the runbooks that have two guides, and the guides about procedures the desk no longer performs. At Meridian Parts the first pass found the drawings guide, with no runbook named on it, and three more like it. All four were re-derived that week. It is worth saying that none of the four had been wrong when written. They had simply been written alone, and documents written alone stay alone.

The Change That Triggers a Review of Both

A pair is reviewed whenever the procedure it describes might have changed. The trick is to make the trigger part of the thing that changes it rather than a thing to remember afterwards. The simplest version is a line on the change record. Every planned change to a shared system gets a one-page record, as described in The One-Page Change Record. And that record gains one field: "documents affected", filled in before the change from the register. A share that is moving has a runbook and a guide. Both are named on the change record; both are reviewed before the change is closed. The drawings share at Meridian would have been caught by that one field.

Not every change arrives through a change record, so there are four more triggers to write down. One is a supplier's update that alters a screen, a menu or a button's name. That changes the guide even when the procedure is the same, because the guide says what the user will see. Another is a run of the runbook that found a step different from what was written. That means the runbook gets fixed and the guide must be re-read against the fix. Another is a ticket in which a user says "the article told me to" followed by something that did not work. That is a user reporting drift. The last is the retirement or renaming of any system, drive, printer or application the pair mentions. That usually changes both documents and sometimes retires the pair altogether.

Each trigger produces the same small action: open the register, find the pair, open both documents, and check them against the change. The action takes ten minutes when the trigger fires and an afternoon when it is discovered five months later from nine weekend tickets. The person who makes the change does the check, because they are the person who knows what changed. If the register names a different owner for the pair, the changer tells the owner, in the ticket or the change record. In that case, the owner does the check. Either way it is done before the change is closed, not after. "After" is a word that means "never" in a queue with fourteen tickets in it.

The Review That Checks Both

Besides the triggered reviews, every pair is reviewed on a schedule. The schedule belongs inside the knowledge base's existing quarterly sweep rather than alongside it. The sweep that marks stale articles, retires dead ones and checks that every article still has an owner is described in Maintenance Without a Documentation Day. The sync check is one more column on that sweep, applied to the articles that are halves of a pair. A pair is checked in three steps, and the order matters.

First, read the runbook's last-run line. If it has been run since the last review, the runbook is probably true and the check is quick. If it has not been run in six months, run it, against a test system or in a quiet window. A runbook nobody has run is a runbook nobody has checked. Reviewing the guide against an unchecked runbook is checking one guess against another. Second, open the guide beside the runbook and the mapping, and read each guide step against the runbook step it came from. Check for the same action, the same order, and the same "what you will see". Check that nothing in the guide lacks a runbook line behind it. Third, read the guide alone, as a user, and look for anything a user would now see differently. That could be a renamed button, a drive letter, or a screenshot of a screen that has changed.

The review ends with a date on both documents and a line in the register. "Reviewed together, both current" is the usual outcome and takes fifteen minutes a pair. "Guide re-derived" or "runbook step four rewritten, guide step two reworded" are the others. On a desk with twenty pairs, the whole sync check is a morning a quarter. It is one of the few mornings in a help desk calendar that reliably prevents more work than it costs. I say that as someone who has spent the other kind of morning closing nine tickets about a drive letter.

Drift Signals in the Queue

Between reviews, the queue will tell you when a pair has drifted, if you ask it the right questions. The clearest signal is a ticket that quotes the article: "the article says", "I followed the guide and", "step three tells me to". One such ticket is a user who misread. Three in a month about the same article is a stale guide. Mark those tickets so they can be found together; many tools can link related tickets to one another. The linked set, with the article's number in the first one's notes, is the evidence that the guide is wrong and the measure of what it is costing. If you run QuerySolv, linking the nine weekend tickets to each other turns nine small jobs into one visible fact with a count attached. That count is what gets the article fixed before lunch.

The second signal is the "already tried" line. Users who read a guide arrive at the desk saying what they tried. When what they tried is no longer in the runbook, or never was, the guide has a step the runbook does not. The third is the failed search: a user searching for the new drive letter, or the new button name, and finding nothing. That is because the guide still uses the old one. The fourth is quieter: a guide whose views fall to nothing while tickets about its subject continue. That means users have learned the article is wrong and stopped opening it. Reading those numbers properly belongs to the self-service measurement series in this library. Here the point is that each one is a trigger, and the table below says what to do when it fires.

Who Owns the Pair

One person owns the pair, and it is the person who owns the runbook, because the runbook is the source of truth and the guide follows it. Owning the pair means being the name on both documents and the name in the register. It means being the person the change record names in "documents affected" and the person who does the quarterly check. It does not mean writing every word of the guide; the owner decides the steps, and anyone can improve the words. It does mean that when the share moves, there is exactly one person who should have thought of the guide. That person is the one who updated the runbook. The principle that every article has a name on it, and what happens to articles that do not, is in Ownership: Every Article Has a Name on It. The pair is the case where one name covers two articles on purpose.

When the owner leaves, the pair is handed over as a pair. The leaver's register rows get a new name. The new owner runs each runbook once in their first month, and reads each guide against it. That is both the handover and the best induction a new technician can have. A pair that is handed over as two documents to two people has been split, and will drift within the quarter. A pair handed over as one row in a register to one name stays a pair.

Split ownership does happen, usually when the guide is published by a communications or training function that owns the portal's words, and the runbook by the desk. It can work, with one condition: the guide's owner may change wording and never steps. As part of that condition, the runbook's owner tells the guide's owner about every change, in writing, through the register. Without that condition, the two owners each believe they are keeping their half current, and both are right, and the pair drifts anyway.

A Short War Story: The Button That Moved at Thornbury Opticians

Thornbury Opticians ran thirty-one branches on a practice management system. The supplier's update renamed the "Sync now" button to "Refresh" and moved it to a different menu. The desk technician, Jo, updated the agents-only runbook for "Branch appointments not updating" the same afternoon, because she was following it when she noticed. The published guide, written from memory by a former colleague two years earlier and linked to nothing, continued to tell branch staff to click "Sync now". Over the following three weeks twenty-eight branches raised tickets saying the button did not exist. Several had first clicked everything else in the old menu. One of those clicks reset the appointment display to a layout from a decade before and cost that branch a morning. Every ticket was closed within ten minutes with "click Refresh, it is under the View menu now", and none of them was connected to the next. Then a branch manager replied to her closed ticket asking why the desk kept answering the same question instead of fixing the article. That was the first time anyone at the desk had read the article. Jo built the register that week and found eleven guides with no runbook named on them. She re-derived them and added the "documents affected" line to the change record form. The fix to the guide, when it was finally made, took four minutes. The three weeks had cost about thirty hours of desk time and one branch's morning. And the cause was not that anyone had failed to update a document. It was that nobody knew there were two.

The Sync Register

The register below is the template for this article. It has one row per pair, is kept where the desk keeps its other registers, and is opened before any change that touches a system a pair describes. The columns that matter most are the trigger systems, because they are what connect a change record to the pairs it affects, and the two "last" dates. A pair whose runbook was last run a year ago and whose guide was last reviewed last week has been reviewed against a guess. Build it in one sitting from every runbook and every guide, pairing what pairs and flagging what does not. Then keep it current at the quarterly sweep and on every triggered review.

SYNC REGISTER — ONE ROW PER PAIR
Desk: ______________   Kept by: ______________   Last full review: ________

RULES
  The runbook is the source of truth. Guide steps change only after the
  runbook changes. Wording in the guide may be edited by anyone.
  Open this register before any change to a system named in it.

PAIR
  Runbook ID: RB-____   Title: __________________________________________
  Guide ID:   G-____    Title (user's words): ____________________________
  Owner (one name for the pair): ______________
  Mapping: guide step 1 = RB step __  step 2 = RB step __  ends before RB step __
  Trigger systems (server, service, application, device, share):
    ____________________  ____________________  ____________________
  Runbook last run: ________ by ________ ticket ________
  Guide last reviewed against runbook: ________ by ________
  Last change record naming this pair: ________
  Drift signals open (linked ticket group, if any): ______________
  Status: [ ] in sync  [ ] runbook changed, guide pending  [ ] re-derive guide
          [ ] retire pair (system gone)   Due by: ________

PAIR
  Runbook ID: RB-____   Title: __________________________________________
  Guide ID:   G-____    Title (user's words): ____________________________
  Owner: ______________
  Mapping: guide step 1 = RB step __  step 2 = RB step __  ends before RB step __
  Trigger systems: ____________________  ____________________
  Runbook last run: ________   Guide last reviewed: ________
  Status: [ ] in sync  [ ] guide pending  [ ] re-derive  [ ] retire   Due: ________

(one block per pair; sort by trigger system when planning a change)

UNPAIRED (found at review; resolve each)
  Guide with no runbook named: G-____ ______________  action: ______________
  Runbook with user side but no guide: RB-____ ______________  action: ________

TRIGGERS THAT OPEN THIS REGISTER
  [ ] A change record touching a trigger system     [ ] A supplier update changing a screen
  [ ] A runbook run that found a step different     [ ] A ticket quoting an article
  [ ] A system, share, printer or application renamed or retired
  [ ] The quarterly sweep

Hamid built the register at Meridian Parts on the Monday afternoon, after the ninth drive S ticket, from eleven runbooks and fourteen guides. It took him two hours. Nine pairs matched. Four guides had no runbook, one runbook had two guides, and one guide described a label printer the company had sold. The drawings folder guide was re-derived from its runbook in twenty minutes. It now says drive P and carries "RB-07" in a note only the desk can see. The change record form has a new line. And the next time a share moves, somebody will fill the line in. And the posters in the lift will go back to being right.

Frequently Asked Questions