From Draft to Published: The Light Review

Wednesday, 14:30, at Bluewater Bank. Grace, who leads the branch support desk, has a list on her second screen. It shows twenty-three desk-only drafts written by her five technicians over the past month, sorted by how many tickets have used each one. Most have been used once, by their author. Three have been used six or more times. The top one, "Counter card reader says TAMPER and will not take cards", has been used eleven times across nine branches. Two of those uses were by cashiers who were read the steps over the phone and did them unaided. Branch staff are still phoning the desk about it. The article that would stop the phone calls exists, is correct, and has been tested eleven times. It cannot be seen by a single cashier, because it is a draft. And it says "re-seat the data cable at the reader end, then power-cycle the reader; if TAMPER persists the unit has locked and must go back to the supplier", which is a technician talking to a technician.

Grace's question is the one every desk reaches a month or two into the capture habit. Which of these drafts should everyone be able to see, who decides, and how much work is it? The method in this series produces drafts quickly and on purpose, and a desk that produces drafts quickly will accumulate them. Some will deserve a wider audience. Most will not, and the desk needs a way to tell the two apart that costs less than the drafts did.

The light review is a ten-minute check by one named person, triggered by a draft having proved itself in use. It asks three questions: is it right, is it safe for a requester to follow, and is it in their words? It ends with the article published to everyone, split into a public and an internal version, or deliberately kept internal. It is the step between the two-minute draft of The Capture Habit and an article a cashier can follow from a branch. And it is light because the heavy work has already been done by the eleven people who used the draft. This article is part of our Capture Knowledge While Solving series, and it is about that step.

It covers the three states an article can be in and why the middle one matters. Next comes who reviews and why it is one person rather than a committee, then what triggers a review: reuse rather than the calendar. We cover the ten-minute review and its three questions, then the user-safe rewrite and the article that should stay internal. Next come telling people the article exists and what happens to a published article afterwards. A short war story follows, then the promotion checklist to copy.

Three States, Not Two

An article is in one of three states. It can be a draft the desk alone can see, a reviewed article that is still internal on purpose, or a published article that everyone can see. Most knowledge base tools offer the first and the third as a visibility setting. Desks tend to treat them as the only two options, which leads to one of two failures. Either every draft is published as soon as it is written, because publishing is the default. Then requesters follow rough technician notes with predictable results. Or nothing is ever published, because publishing feels like a commitment nobody has time to make. Then the knowledge base becomes a private notebook that saves the desk time and the requesters nothing.

The middle state is what fixes both failures, and it is a decision rather than a setting. A reviewed-internal article is one that somebody has looked at with the three questions and concluded should stay with the desk. That could be because it needs administrator rights or because it contains detail about the bank's systems that does not belong on a portal. Or it could be because no requester could do the steps anyway. It is not a draft. It is finished, trusted, owned, and internal, and the review note at the top says so. That way nobody reviews it again next month wondering why it was never published. If you run QuerySolv, each article is visible either to agents only or to everyone, which maps onto the first and third states directly. The middle state is a line at the top of the article saying who reviewed it, when, and why it stays internal. The same line works in any tool.

The picture below shows the three states and the review between them, with the trigger that moves a draft into review and the two ways out. The important thing to see is the shape: one review, two exits, and a draft that nobody reuses never enters the review at all. There is no step where the desk reviews all twenty-three drafts. There is a step where it reviews the three that have earned it.

Who Reviews: One Named Person, Not a Committee

The reviewer is one person, named in advance, and never the author. It is one person because a review that needs two people to agree needs a meeting, and a meeting is a documentation day with chairs. The review that waits for the knowledge committee waits for the knowledge committee's next quorum, which on a desk of five is a date with no fixed meaning. It is never the author because the author cannot see what they left out. They wrote "re-seat the data cable" knowing which end, which cable and which way up. The review exists to find the places where that knowledge did not make it onto the page.

On most small desks the reviewer is the lead, or whoever owns the area of the knowledge base the article belongs to. The choice should be written down so that a draft never waits for a volunteer. A desk with a lead and five technicians might say the lead reviews anything about branch hardware. In that arrangement, Priya reviews anything about the core banking system because she knows it best, and anything else goes to the lead. The point is that for every draft that earns a review, there is one name that should do it. There is a second name if the first is away. A draft that has been used eleven times and is waiting for "someone" to review it is waiting for nobody.

The reviewer becomes the owner, or names one, and that is the review's last act. A published article has a person responsible for it from the day it goes out. That person gets the flags, makes the edits that technicians cannot, and notices when the screens change. Why every article needs that name, and how to keep the list short on a desk where everyone is busy, is the subject of Ownership: Every Article Has a Name on It. Here it is enough that the review does not end until the name is on the article. Often it is the author's name. Sometimes the reviewer takes it. It is never blank.

What Triggers a Review: Reuse, Not the Calendar

A draft is reviewed when it has proved itself, and the proof is in the linked tickets rather than in the author's opinion or the date. Three signals, any one of which is enough. The draft has been used on three or more tickets, which means the symptom recurs and the steps have been tested by someone other than the author. A requester has followed the steps and they worked, which means the article is already doing a user-facing job without having been written for one. Or triage would have sent the article in the first reply if it had been published, which means the desk is paying for its absence on every ticket.

Reuse is the trigger because it is the only signal that is free, honest and automatic. A desk reviewing on the calendar reviews everything, including the twenty drafts that have been used once, and the review takes a day and does not happen. A desk reviewing on the author's request reviews the drafts the authors are proud of, which is a different set from the drafts the queue needs. A desk reviewing on reuse reviews the three drafts the tickets have already pointed at, and the review takes half an hour a month. The linking convention from Refine on Reuse is what makes the list on Grace's screen possible. The convention is the article's number written the same way in every resolution note. A desk that skips the link cannot sort by reuse and so cannot run this review.

The drafts that never trigger a review are not a problem. They were written in two minutes. They cost nothing to keep. And one of them will be the article that saves a new starter forty minutes next spring. Do not clear them out, do not review them for tidiness, and do not count them as a backlog. A knowledge base with two hundred desk-only drafts and thirty published articles is a knowledge base working as designed. The ratio says only that most symptoms do not recur often enough to need a public article, which was always true.

The Ten-Minute Review: Three Questions

The review asks three questions in order, and each one can stop the process. Is it right? Is it safe for a requester to follow? Is it in their words? The first is a check against the evidence; the second is a check against harm; the third is a check against the reader. Ten minutes is enough for all three on a draft that has been through several uses. The uses have already found most of the errors. The reviewer is reading an article that eleven people have followed rather than one that nobody has.

The three questions are deliberately not a checklist of everything an article could be. There is no question about screenshots, formatting, length, tone or whether a video would help, because those are matters of craft. The craft of a followable article has its own article in The Article Review Checklist Before Publishing. The reviewer may use it after the three questions have been answered yes. The light review is the gate. The craft checklist is what the article gets once it is through the gate and is worth the time. A desk that applies the craft checklist to every draft reviews nothing, because nobody has that afternoon.

"Is it right?" is the question reviewers skip, on the grounds that eleven uses must mean it works. It is worth the two minutes anyway. Eleven uses can mean eleven technicians who each knew the real step and ignored the written one. That is the rot described in Refine on Reuse. The reviewer finds it by reading two of the linked tickets and checking that what was done matches what is written. The reviewer at Bluewater found that the card reader article said "power-cycle the reader". Three of the tickets said "power-cycled at the wall, not the reader's own switch, which does nothing". One line fixed it before the cashiers ever saw it.

The User-Safe Rewrite

The user-safe rewrite turns a technician's draft into an article a cashier can follow at a branch counter with a queue behind her. It changes four things. The title becomes what she would say: "Card reader shows TAMPER and won't take cards" rather than "Counter card reader TAMPER state". The steps she can do stay and are rewritten as one action each, naming what she will see. One example is: "Unplug the thick black cable from the back of the reader, wait five seconds, and plug it back in firmly until it clicks." The steps she cannot do go, and are replaced by one line. That line says: "If TAMPER is still showing after this, call the desk and say you have followed this article; the reader needs to be replaced." And the explanation of the cause shrinks to one sentence or disappears. She does not need to know why the reader locks, only what to do when it does.

This produces two documents from one draft, and that is the intended result, not a duplication. The internal version keeps the technician's detail. That includes the supplier's return process and the reader's model numbers. It includes the fact that the wall socket is the one to use and the reason, and the note about branches with the older counters. The public version has the four steps and the line about calling the desk. The two describe the same symptom and the same fix at two depths, for two readers. And Two Audiences, Two Documents explains why trying to serve both with one document serves neither. The mechanics of deriving the public version from the internal one, and of keeping the pair aligned when one of them changes, are in Writing the User Guide From the Runbook.

The rewrite takes about ten minutes for a short article. And the reviewer can do it or hand it back to the author with the three questions answered. I prefer the reviewer to do it, because the author will unconsciously put the technician's detail back. The reviewer has just read the linked tickets and knows which words the requesters actually used. Those words, from the ticket subjects and the first messages, are the best source for the title and the first line. The requesters have been writing the public article's title for weeks, one ticket at a time. And the rewrite is mostly a matter of listening to them.

The Article That Should Stay Internal

Some drafts, having proved themselves, should be reviewed and then kept where only the desk can see them. And this is a good outcome rather than a failed review. The clearest cases are articles whose every step needs rights a requester does not have. So publishing them would produce a page of instructions nobody reading it could follow. Next are articles that describe the organisation's systems in detail a portal should not carry. That includes server names, internal addresses, how the sign-in system is arranged, where the backups go. Then come the articles whose fix would be harmful in a requester's hands. An example is a workaround for a known error that is safe when a technician does it with the context and unsafe without it. And last, articles about the desk's own procedures, which are runbooks and were never meant for anyone else.

The decision is recorded on the article so that it is made once. A line at the top can say "Reviewed by Grace; stays internal: requires administrator rights at every step". That means next month's list does not put the article up for review again. The next technician to use it does not wonder whether to send it to a requester. Without the line, the same article is re-examined every time it climbs the reuse list. The desk spends ten minutes a month reaching the same conclusion. The rules about what must never appear in a document a requester can see are stricter and longer than this paragraph. And What Must Never Be in the User Document is the full list. The reviewer should read it once and will then recognise the cases on sight.

The commonest mistake is publishing an article because it is good rather than because it is useful to a requester. A beautifully written article on recovering a locked card reader via the supplier's portal is a pleasure to read. No cashier will ever act on it, because no cashier can. It stays internal, it is used by the desk every week, and its public counterpart is four steps and a phone number. Good is not the criterion. The criterion is whether the person reading it can do what it says.

Publishing: Tell People It Exists

An article that is published and announced to nobody has been filed. The desk will go on answering the same question by phone for a month while the answer sits on the portal. Publishing has three small acts attached to it, each taking a minute. The desk is told, in one line in the team chat. The line says: "Published: card reader TAMPER article, KB-204; send it in the first reply from now on." Triage adds it to whatever list it keeps of articles that answer common tickets. So the next cashier who phones is sent the link within the hour rather than walked through the steps. And the article is put where requesters will meet it at the moment of need. For the card reader, that means the portal's page for branch equipment. It also means, if the desk has one, the message requesters see while they are typing a new ticket.

The last of those is the only one that stops tickets being raised at all. And it depends on requesters using the portal in the first place, which is a larger subject with its own series. Promoting the Portal Without Nagging covers how to get requesters there. The point for the reviewer is that a newly published article is the best possible reason to mention the portal. That applies to the people who have been phoning about that symptom, because the article answers the question they actually had. "There is now a page for this; here it is" is the one portal promotion nobody resents.

The first reply is where a published article earns most of its value in the first months, and the phrasing matters. "This is a known problem with the counter readers and there is a short article on fixing it yourself: [link]. It takes about two minutes. If TAMPER is still showing afterwards, reply to this ticket and we will arrange a replacement." The requester has the fix, a time, and a route back if it fails. The ticket is resolved when they confirm. If they reply instead to say it did not work, the ticket reopens and the desk knows the article failed on a real case. That is information the owner wants.

After Publishing: Still Refined on Reuse

A published article is not finished; it is finished being a draft. The world will go on changing underneath it. The card readers will be replaced with a model that says LOCKED instead of TAMPER. And the article will need the same one-line corrections that kept the draft alive. What changes at publication is who makes them. Technicians who find a published article wrong flag it at the top for the owner, in the internal version, rather than editing the public text themselves. A public article is read by people who cannot judge a half-finished edit. The owner makes the change, usually the same day, and the flag comes down.

The other change is that requesters now become reviewers too, without knowing it. Every requester who follows the article and replies "that didn't work" is a test the desk did not have to run. And the reply arrives on a ticket, where it can be read, linked and counted. In QuerySolv a requester's reply to a resolved ticket reopens it, and most tools behave the same way. So a failed article comes back as a reopened ticket rather than as silence. Three reopens in a month on tickets that were sent the same article is the owner's signal to open the article and the tickets side by side. The owner should then find out what the requesters are seeing that the article does not describe.

Owners should also expect the pair to drift and should check it when either half changes. A correction to the internal version that is not carried into the public one produces two articles that disagree about the same fix. So does a public rewrite that quietly contradicts the technician's steps. The technician on the phone with a cashier reading the public one will find out. Keeping the two aligned is a small, regular discipline, and Keeping the Pair in Sync describes the simplest version of it. The owner's name on both articles is what makes it anyone's job.

A Short War Story: The Boatyard Wi-Fi at Kestrel Marine

Kestrel Marine, a boatyard and chandlery with about sixty staff, ran its help desk with two technicians. One of them, Callum, wrote a quick draft for connecting the yard's laptops to the workshop wireless network after a technician had done it a dozen times. The draft's fourth step, written for himself, said "turn off the security software while you connect, it blocks the first handshake, turn it back on after". The knowledge base had only one visibility setting, which defaulted to everyone. So the draft was published the moment it was saved. Over the next six weeks eleven yard staff found it by searching for "workshop wifi", followed it, connected successfully, and did not do the last part. The article had not said what "turn it back on" looked like and the connection worked without it. The twelfth laptop, with its protection off for a month, picked up malware from a customer's memory stick full of boat photographs. The clean-up took the two technicians most of two days. After that, the yard's insurer sent a questionnaire about endpoint protection that took the owner a further afternoon. Callum's draft was correct for a technician and dangerous for anyone else, and nobody had asked the second question before it went out. A knowledge base that publishes by default has no drafts, only articles that have not hurt anyone yet.

The Promotion Checklist

The checklist below is the light review as a page, to be filled in by the reviewer and kept with the article or in the review note. It has the trigger at the top, so that the review records why it happened. Then come the three questions as tick boxes, then the decision and the owner. It is designed to take ten minutes on a draft that has been through several uses. If it is taking thirty, the draft was not ready and should go back to the author with the first unticked box as the reason. The last line, "told the desk", is the one that gets forgotten and is the one that makes the rest worth doing.

THE PROMOTION CHECKLIST — FROM DESK-ONLY DRAFT TO PUBLISHED
Article: ________   Author: __________   Reviewer: __________   Reviewed: ________

WHY IT IS BEING REVIEWED
  [ ] Used on ____ tickets        [ ] A requester followed the steps and they worked
  [ ] Triage would have sent it   [ ] Other: ___________________________________

1. IS IT RIGHT?
  [ ] The linked tickets agree with the written steps
  [ ] The cause line is confirmed, or says "not yet known"
  [ ] The check that proves the fix is written down
  [ ] Nothing on the draft's "not yet" list is still open and important
  Any box unticked: back to the author with the box named. Stop here.

2. IS IT SAFE FOR A REQUESTER TO FOLLOW?
  [ ] No step needs administrator rights or a technician's tools
  [ ] No credentials, server names, internal addresses or security settings
  [ ] No step could affect anyone other than the requester
  [ ] No step disables a protection, even briefly
  Any box unticked: stays internal, or split into public and internal versions.

3. IS IT IN THEIR WORDS?
  [ ] Title is the symptom as a requester would say it
  [ ] One action per step; the thing to click is named as it appears on screen
  [ ] Says what they will see when it has worked
  [ ] Says what to do if it has not: reply to the ticket and mention this article
  Any box unticked: user-safe rewrite, by reviewer or author, then publish.

DECISION
  [ ] Publish to everyone
  [ ] Stays internal. Reason, written at the top of the article: ________________
  [ ] Split. Public version: ________   Internal version: ________
  Owner from today: __________   Told the desk: [ ]   Linked from: ________________

Grace reviewed the card reader draft at 14:40 and had finished by 14:52, most of which was the rewrite. The internal version kept the supplier's return steps and the note about the wall socket. The public one had four steps, a sentence about what the display would show when it had worked, and the line about replying to the ticket. It went out that afternoon with one message to the desk and one to the branch managers. The phone calls about TAMPER dropped to a handful a month, each of them a reader that genuinely needed replacing. The other twenty drafts on her list stayed drafts, which was the right place for them. The review of the next two took her twenty minutes the following Wednesday.

Frequently Asked Questions