The Article Review Checklist Before Publishing

Friday, 16:10, at Oldbury Print. Farah runs the desk and, because somebody has to, edits the knowledge base. Nine drafts are waiting for her from a week in which the team was asked to write one each. The one at the top is "Scanner Setup", from Ben, who has been on the desk a month. She reads it in two minutes. The title is a filing label. There is no line saying who it is for. Step 4 says "configure the destination as normal". The one screenshot shows Ben's own mailbox behind the scanner dialog, with his inbox subject lines in plain view. The link in the last line goes to the old portal, which was switched off in the spring. There is no owner on it and no date. None of this is Ben's fault; nobody told him what a finished article looked like, and he wrote what he knew, which is the thing writers do. Farah could fix it herself in twenty minutes. She has nine of them, and it is ten past four on a Friday.

The editor's pass is the last read of an article before it goes public, done by someone other than the writer. It follows a fixed list of questions that is the same for every article. It is not the hallway test, which checks whether a stranger can follow the steps, and it is not a technical review, which checks whether the steps are true. It is the check for everything else: the title that cannot be found, the audience that is not named, and the picture that leaks. It checks for the link that is dead and the article that nobody owns. This article is part of our Writing KB Articles People Can Actually Follow series. And it is about that last five minutes, and the list that makes them the same five minutes every time.

It covers why there is an editor and why the editor has a checklist. It covers the pass in order, from title and audience, through steps and results, then screenshots and links. Next come what must not be there and the owner and review date. We cover the common failures and the fix for each, then what happens after publishing. We finish with a short war story and the checklist itself to copy, in that order.

Why an Editor, and Why a Checklist

The writer cannot see their own article, and the tester sees only whether it can be followed. So a third pair of eyes is needed for the things neither of them is looking for. The tester does not notice that the title duplicates an article that already exists, or that the screenshot shows real data in its margin. They do not notice that the link goes to a portal that no longer exists, or that the article has no owner. The tester is following steps and all of those are invisible while you follow steps. The writer does not notice them because the writer wrote them. The editor is the person who reads the article as an article, with the whole knowledge base in mind, and asks whether this one belongs in it.

The editor works from a checklist because the pass has to be the same for every article and every editor. An editor without a list reads for whatever is on their mind that day. One Friday it is screenshots, the next it is tone, and the dead link goes through on both. A list of fixed questions, asked in a fixed order, takes about five minutes per article. It finds the same failures whether the editor is the lead, the second technician on a rota, or the person who inherited the knowledge base last month. The list is at the end of this article. The rest of the article is the reasoning behind each line of it. An editor who understands why a question is asked can judge the edge cases the list does not cover.

Who the editor is matters less than that there is exactly one at a time. On a desk of three, it is usually the lead; on a desk of eight, a rotating second person works, as long as the rota is written down. The arrangement where every article has an owner and the knowledge base as a whole has an editor, and what goes wrong when either name is missing, is the subject of Every Article Has a Name on It. The flow that brings a draft from an agents-only note written during a ticket to the editor's desk is described in From Draft to Published. This article picks up where that flow hands over: the draft is in front of the editor, and the question is whether it goes out.

Title and Audience

The editor's first question is whether the title is the question a reader would type, in the reader's words. "Scanner Setup" is not; "How do I scan a document to my e-mail?" is. The editor checks this by imagining the reader at the search box, or better, by asking the nearest non-technician what they would type. The fix is to retitle, which the editor can do without sending the draft back. The second question is whether the article already exists under another name. And the editor answers it by searching the knowledge base for the reader's words before reading any further. A duplicate article is worse than none, because the two will diverge, and the reader will find the wrong one. If a duplicate exists, the new draft becomes an edit to the old article, not a second article.

Then the audience line: is there one, is it specific, and does the article's visibility match it. "For anyone who uses the office scanners" is an audience; an article with no line at all will be followed by the people it is not for. The editor checks visibility from the audience line, not from habit. An article for technicians is published to agents only; an article for users is published to everyone. An article that says "for technicians" and is visible to everyone has just published its admin steps. The desk may serve several departments with their own request forms, as QuerySolv departments each have. In that case, the editor also checks that the article belongs to the department whose readers will search for it. An HR article filed under IT is an article HR's readers will never see.

The common failure here is not a bad title but a reasonable one written from the inside: the system's name, the technician's verb, the project's codename. The fix is always the same, and the editor can make it alone. Rewrite the title as a question with the reader's verb at the front, and put the system's name at the end if it is needed at all. Check the result by saying it aloud. If it sounds like something a person at a desk would say, it passes. If it sounds like the heading of a procedure document, it does not. (Procedure documents are where articles go to be unread.)

Steps and Results

The editor reads the steps for shape, not for truth; truth was the technical reviewer's job and followability was the tester's. Shape means: one action per step, each starting with a verb, each naming its control by the words on the screen, each followed by a result line. The editor's eye runs down the left edge looking for numbers and verbs. It runs down the step text looking for "and", "then", "as normal", "as appropriate", "simply", "just" and "etc." Any of those marks a step that has to go back to the writer. A step without a result line goes back too, because the editor cannot write what the reader should see without doing the task, and the writer can.

The editor also asks for the test sheet. An article that has not been through at least one hallway test is not ready for the editor. The editor's correct response is to send it back with the test sheet attached rather than to read on. The stalls a tester finds will change the steps, and the editor would be reviewing a draft that is about to be different. The test and its sheet are in Testing Articles on Real Users, and the rule for the editor is simple: no sheet, no pass. This is the line on the checklist that desks most want to skip, and it is the one that saves the most tickets.

Before leaving the steps, the editor reads "before you start" against them. The editor looks for the prerequisite that appears at step 6 and nowhere at the top. That might be a role, a file, a cable, a code, or a time by which the task must be done. The editor reads the end for the finished-result line, the "if it did not work" section and the "who to contact" route. Between them, those are the three parts most often missing from a draft written by someone who has only ever done the task successfully. An article that ends at the last step has not ended; it has stopped.

Screenshots and Links

Every picture gets the screenshot checklist. The editor runs it with more suspicion than the writer did. The editor is the one who will be asked why the finance director's inbox was on the portal. Does the picture earn its place, or does it show what the text just said? Is it cropped to one thing? Is there one mark on it, around the control the step names? And, most carefully, what is in the margins: the window title, the tabs, the taskbar, the list behind the dialog. Ben's scanner screenshot failed on the last question, and it is the question editors most often skip because they, like the writer, are looking at the control. The full checklist, and the reasoning behind each line, is in Screenshots That Help, and the Ones That Do Not.

Every link gets clicked. It is not read but clicked, from the editor's own browser, and ideally from an account that is not the editor's. A link that works for the editor may lead to a page the reader cannot see. The common failures are the link to a portal that has been replaced and the link to a document on someone's personal drive. They include the link to another article by a title that has since changed, and the link in "who to contact" that goes to the wrong form. Each is thirty seconds to find and thirty seconds to fix, and each, unchecked, is an article that ends in a wall. The war story below is about one such link, and it was not an unusual one.

The editor also checks that links go to the right level. An article that explains a sub-procedure inline when another article already owns it should link instead, so that there is one place to fix when the sub-procedure changes. An article that links to a procedure in the middle of its own steps should say "then return here for step 5", so the reader comes back. Links to other articles are by title, so the reader knows what they are clicking, and never "click here". The last link the editor checks is the escape hatch: a route and a time, not a department, reachable at the hours the article will be read.

What Must Not Be There

The editor reads once more for the things that should not be in an article users can see. This read is the one the writer is least able to do, because the things that leak are the things the writer takes for granted. These include administrative paths and console names, internal server names and addresses, a credential, a shared password, or a code that bypasses a check. They include a step that only works with elevated rights, written as if anyone could do it. They include the name of a supplier or a contract the organisation does not publish, or a real person's data in a picture. The test for each, and the longer list, is in What Must Never Be in the User Document. The editor runs it on every public article and does not publish until it passes.

The second category is less dangerous and more common: things that make the article worse without making it unsafe. Paragraphs of reason before the first step. Sentences that blame the reader. Exclamation marks and jollity. Jokes belong in articles like this one and never in articles like Ben's. A joke in an instruction is a stall for the reader who did not get it and an irritation for the reader who did. Both of them have a scanner that is not working. Apologies from the article. And the sentence that announces the next sentence. The editor cuts these without consultation, because none of them carries information the writer would miss.

The third category is the article that is really two. The steps may fork more than once, there may be two "before you start" lists, or the title may have "and" in it. Or the article may run past about a dozen steps and the editor can see a natural seam. In any of those cases, the editor sends it back with a line drawn across the seam and a suggested title for each half. Two short articles are found by two searches and maintained by two small edits. One long article is found by neither search and maintained by nobody, because the person who could fix half of it does not feel entitled to touch the rest.

Owner and Review Date

An article goes out with a name on it and a date it was last checked on the live system. It also has a date by which someone will check it again. The name is the owner, the person who will fix it when a ticket says it is wrong. The owner is a person, not a team, because teams do not open articles. The checked date tells the reader and the editor how far to trust it. The review date is the alarm, and the editor sets it on the article's behalf from what the article depends on. An article about a system due to be upgraded gets a review date just after the upgrade. An article about a policy gets one at the policy's review; an article about a stable thing gets a longer interval. An article with no review date will be reviewed when a user complains, which is the most expensive possible time.

The editor also writes down, on the article or in the register, which system the article depends on. That way, a change to that system produces a list of articles to check rather than a memory that there might be some. Ben's scanner article depends on the scanners and on the mail system; when either changes, somebody needs to know that this article is one of the ones to reread. That link between change and review, and what happens to the article whose owner leaves, are the business of the Knowledge Base Fundamentals series. The editor's job at publishing time is to make sure the fields are filled in. That way, the later process has something to work with.

The Common Failures and the Fix for Each

The table below is the editor's pass as a list of the things that actually come through, in rough order of how often. The last column is the decision the editor makes on each. The editor fixes it in place for anything that needs no knowledge of the task. The editor sends it back for anything about the steps, because the writer has the knowledge and the editor has only the list. The rule keeps the editor from becoming the desk's rewriter, which is the role editors drift into and the reason they stop editing.

Publishing, and the Day After

When the article passes, the editor publishes it, tells the desk in one line, and books the published-version check for the next day. The line to the desk is "Published: 'How do I scan a document to my e-mail?', for all users; point people at it," and it takes ten seconds. It means that for the next week every technician answers that question with a link instead of a paragraph. That is both faster and the first test of whether the article works in the wild. Publishing silently is filing, and filed articles are read by their authors.

The next-day check is the editor's, not the writer's. And it is done from a user's account: search for the article with a user's words, open it on a phone, and click the links again. And confirm that the pictures and the numbering survived the trip into the knowledge base. Then the editor's job is done until the first ticket arrives that the article should have prevented. That ticket is not a failure of the pass. It is the fourth tester, and its one-line finding goes to the owner, whose name is on the article precisely so that this moment has somewhere to go.

A Short War Story: The Quick One at Acme

At Acme, an article called "How do I request an account for a new starter?" was written on a Thursday afternoon by Oliver, the desk lead. He was also the editor. He published it himself without running his own checklist because it was four lines long and he had written it. Its single link, "use the new-starter request form", pointed at the form on the test portal that the desk had used while trying out the ticketing tool. The test portal still existed, still accepted submissions, and sent them to a queue that nobody had opened since the trial ended. Over five weeks, twenty-three managers followed the article, filled in the form, and received a cheerful automatic confirmation from the test system. They told their new starters that IT had it in hand. Eleven of those new starters arrived on their first day with no account, no e-mail and no laptop. They sat in reception while their managers phoned a desk that had no record of them. HR raised it with the operations director after the fourth. The desk found the twenty-three submissions only when someone finally wondered why the test portal was still running. The cost was eleven people's first mornings, twenty-three managers who now double-check anything the portal tells them, and a conversation with the director that Oliver describes as formative. Clicking the link would have taken thirty seconds; the article had been too short to check.

The Article Review Checklist

The checklist below is the editor's pass on one page, in the order the editor reads. It is designed to take five minutes on an article that is nearly ready and to stop early on one that is not. The first section ends with a line that sends the draft back before the editor has read the steps. And the test-sheet line does the same. Every unticked box is either a fix the editor makes in place or a line in the note back to the writer. And the last section records the decision so that nobody later has to wonder whether this article was ever reviewed. Keep the filled-in sheet with the article; it is the article's birth certificate.

ARTICLE REVIEW CHECKLIST — THE EDITOR'S PASS, ONE PAGE
Article: ______________________________________   Writer: ____________   Editor: ____________
Date: ________   Draft version: ____   Test sheet attached?  [ ] yes   [ ] no: RETURN, do not read on

TITLE AND AUDIENCE
  [ ] Title is the question the reader would type, verb first, system name last or absent.
  [ ] Said aloud, it sounds like a person at a desk, not a procedure heading.
  [ ] Knowledge base searched for the reader's words: no existing article covers this.
      If one does: STOP; merge into it and return.
  [ ] Audience line present and specific: who this is for, and who should read what instead.
  [ ] Visibility matches the audience: users' article visible to everyone, technicians' to agents only.
  [ ] Filed under the department whose readers will look for it.

STEPS AND RESULTS
  [ ] "Before you start" lists every right, item and condition needed at any step, with how to check.
  [ ] Every step is one action, starts with a verb, names its control by the words on the screen.
  [ ] No "and" or "then" inside a step; no "as normal", "as appropriate", "simply", "just", "etc."
  [ ] Every step has "You should see: ______".
  [ ] Finished-result line present: "When you have finished, you should see ______."
  [ ] "If it did not work" present, with the one or two likely failures and their fixes.
  [ ] "Who to contact" is a route and its hours, not a department or a person's name.
  [ ] At most one fork; sub-procedures are links with "then return here for step __".

SCREENSHOTS
  [ ] Each picture earns its place: shows where, what to see, or what it looks like.
  [ ] Cropped to one thing; one mark around the control; caption and alternative text written.
  [ ] Margins checked: window title, tabs, address bar, taskbar, list behind the dialog.
  [ ] No real person, customer, patient or deal anywhere in the frame.

LINKS
  [ ] Every link clicked from a non-editor account and reaches the live page.
  [ ] Other articles linked by title; no "click here"; no personal drives; no test portal.
  [ ] Escape hatch link reaches the right department's form.

WHAT MUST NOT BE THERE
  [ ] No admin paths, internal names, credentials, bypasses, or elevated-rights steps.
  [ ] No reasons before step 1; no blame; no exclamation marks; no jokes; no apology.
  [ ] Not two articles in one. If it is: return with the seam marked and two titles.

OWNER AND DATES
  [ ] Owner is a named person.                     [ ] Date last checked on the live system: ________
  [ ] Review date set from what it depends on: ________    [ ] System(s) it depends on: ______________

DECISION
  [ ] Publish        [ ] Fixed in place and publish (list: ______________________________)
  [ ] Return to writer (lines above marked; test sheet attached if missing)
  Published on: ________   Announced to the desk: [ ]   Next-day check from a user account booked: [ ]

Farah ran the sheet on Ben's scanner article at 16:20 and had a four-line note back to him by half past. The test sheet was missing, and step 4 needed splitting with the real wording. The screenshot had to be retaken on the test account and cropped to the destination field. The link to the old portal had to go. Farah retitled the article herself, added the audience line, and filled in the owner field with his name. He was slightly alarmed by that and then, she thinks, pleased. Ben tested it on Monday morning on two people from the print floor and fixed the step they both stalled at. It was published by lunchtime as "How do I scan a document to my e-mail?", visible to everyone. Its review date was set for the month after the scanners were due for replacement. The other eight drafts took Farah the rest of that afternoon, at about five minutes each. Three went back. Five went out. None of them had a mailbox in it.

Frequently Asked Questions