Writing for the Reader Who Is Already Frustrated

Monday, 09:02, at the Castle Street branch of Bluewater Bank. Sam has three customers in the queue, the first of them here about a loan. The loans system has just told him "Your session has expired" and refused his password twice. He types "loans system session expired" into the portal search on the second screen and gets an article called "Understanding Loans System Access". It opens with a paragraph on the system's role in the bank's lending process. The second paragraph explains why sessions expire, for security. The third says that access "is provisioned through the standard request process" and links to a form. Sam has read for forty seconds, has learned why he is locked out, and has not been told how to get back in. He phones the desk, is eleventh in the queue, and asks the loan customer whether she would mind waiting, which she would. The fix, when he finally hears it, is "sign out fully and sign in again; it happens after the weekend password sync". It is one sentence. It was not on the page.

The frustrated reader is the person who opens a knowledge base article because something has stopped working. They have no time to spare and no particular faith that the page will help. They are not learning. They are repairing, under pressure, and they are judging the article from its first three lines. Most knowledge base articles are written as if the reader were calm, curious and seated. That reader exists, but they are not the one who generates tickets. This article is part of our Writing KB Articles People Can Actually Follow series. It is about writing for the reader who is already cross before they arrive.

It covers the three things that are true of this reader before they read a word. Front-loading the fix, naming the symptom in their words, and the escape hatch to a human follow. Next come the calm tone and the three tones that fail, then telling them what the fix will cost. The article about a problem they cannot fix, a short war story, and the frustrated-reader checklist to copy follow, in that order.

Three Things True Before They Read a Word

Something is broken. The reader did not come to the knowledge base to find out how the loans system works. They came because it stopped, and the stopping is the whole of their interest. Every sentence that is not about making it work again is, to this reader, a sentence in the way. That includes the sentence explaining why it broke, however true, and the sentence explaining the policy, however reasonable. They may want those later. They do not want them before the fix, and they will not read past them to find it.

They are in a hurry. There is a customer at the counter, a meeting in four minutes, a payroll cut-off, a patient, a lorry in the yard. The hurry changes how they read. They take in the title, the first line, the headings, and anything that looks like a numbered step, and they skip everything in paragraphs. An article whose fix is in a paragraph is an article whose fix is invisible to the reader it was written for. If the steps are not visible on the first screen, the reader concludes there are none.

They distrust the page. The last three articles they tried did not help. The one before that was out of date, and this one has a title that sounds like a policy document. They are reading with one hand on the phone, looking for the first sign that this is going to be a lecture. The moment they find it they will stop and call. Trust is not won by the writer's credentials or by thoroughness. It is won in the first three lines by showing the reader that the article knows what is wrong. Those lines also show that the article knows what to do, and is going to say so now. The first screen of an article is the article's first sixty seconds. The same thing is true of it that The First Sixty Seconds says about a conversation with an angry user. What happens there decides whether anything after it is heard.

Front-Load the Fix

The fix goes first, before the reason, before the background, before anything. The title names the symptom, the first line confirms the reader is in the right place, and the first numbered step is on the first screen. "Why does the loans system say 'session expired'? If the loans system shows 'Your session has expired' and will not accept your password, this usually clears in a minute. Step 1: click Sign out at the top right, even though you are already locked out." The reader who arrived cross has, in four lines, been told that the page is about their problem and that it is fixable. They know how long it takes and what to do. Everything else in the article is now being read by someone who is willing to read it.

The background, if the article needs any, goes at the end under a heading like "Why this happens". There the reader who has fixed the problem and is now curious can find it. The reader who has not can ignore it. Most articles do not need it at all. The reason sessions expire is interesting to the person who wrote the policy and to nobody else at 09:02 on a Monday. If a sentence of reason genuinely helps the reader do the step, it goes inside the step as an aside: "Click Sign out (this clears the stuck session, which is why signing in again did not work)." One clause, in the place it is useful, and then on.

Where one cause accounts for most cases, say so in one line before the steps, and give it its own one-step fix. "If you changed your password in the last day, this is almost certainly the cause; sign out and sign in again, and you are done. If that does not help, follow the steps below." The frustrated reader is now out in thirty seconds in the common case. The writer has saved the long steps for the uncommon one. The table below shows the first screen of three articles as a frustrated reader meets it, before and after. The change is never in what the article knows. It is in what it says first.

Name the Symptom in Their Words

The frustrated reader searches for what they can see, and what they can see is the error message, or the thing that is not happening. They type "session expired", "print queue stuck", "cannot reach server", "no sound in meeting room". They do not type "access provisioning", "print spooler", "connectivity" or "AV". The article's title and first line therefore contain the words on the reader's screen, quoted exactly. That way the search finds the article and the reader, arriving, sees their own problem named back to them. "Your session has expired" in quotation marks in the title is worth more than any amount of good writing underneath it, because without it the writing is never reached.

Add a one-line "you are in the right place if" that lists the signs, especially where the same symptom has two causes with two articles. "You are in the right place if the message says 'session expired' and you have not changed your password today. If you changed your password today, see 'How do I sign in after a password change?'" The frustrated reader is often holding the wrong article. The fastest service the right article can do is to send them to it in one line. That is before they have followed five steps that were for someone else. An article that fails to say who it is not for will be followed by the people it is not for.

Quote the message as it is on the screen, including its odd capitalisation and its code if it has one. That is because the reader is matching characters, not meaning. "Error 0x1A: session invalid" is what they see, and "an invalidation error" is not. Where the system shows the message in several wordings, list them. Where the message is in a language the reader does not speak, quote it and translate it in the same line. A message in an unfamiliar language happens with systems that were never meant for the people now using them. The symptom section is not the place for the writer's understanding of the problem. It is the place for the reader's view of it, reflected back.

The Escape Hatch to a Human

Every article has a way out to a person, and for the frustrated reader it appears twice. It appears once near the top, for the reader who cannot afford to try. It appears once at the end, for the reader who tried and failed. The one at the top is a single line: "If you have a customer waiting and cannot try this now, call the desk on 4400 and say 'loans session expired'; they can clear it from their end." It gives the reader with no time a route. It gives the reader with a little time permission to try the steps knowing that the route is still there. A reader who can see the exit is calmer about staying in the room.

The hatch names a route and a time, not a person and not a department in the abstract. "Contact your administrator" is not a hatch. It is a locked door with a sign on it, because the reader does not know who their administrator is. If they did they would not be reading an article. "Contact IT" is barely better. "Raise a ticket from the Help button at the top of this page, or call 4400 between 07:00 and 19:00" is a hatch. Where the ticket comes from a reply rather than a form, say that too. A technician who has answered a ticket by pointing at the article can close it knowing that the requester's reply reopens the ticket. That is true in QuerySolv as in most tools. So the hatch for that reader is the reply button and the article should say so. "If this did not fix it, reply to the ticket and say which step went wrong" is a sentence that keeps the reader inside a conversation that already exists.

Never hide the hatch to push people into self-service. An article might bury "raise a ticket" at the bottom of a long page. A portal might make the reader click through three "did this help?" prompts to reach the form. Neither approach saves tickets. Each converts them into phone calls, and the phone call arrives with the reader angrier than the ticket would have been. The honest version of deflection always leaves a way through, and Deflecting Without Annoying People is about exactly that boundary. The article's job is to make the way through unnecessary for most readers by fixing the problem, not to make it hard to find for the rest.

The Calm Tone, and the Three Tones That Fail

The tone that works on a frustrated reader is calm, plain and brief. That means short sentences, no exclamation marks, no adjectives about the reader's experience, and no comments on the difficulty of the task. It sounds like a competent colleague who has seen this before and is not worried, which is exactly what the reader needs to hear. The desk's voice across all its writing is the subject of the Support Tone and Voice series. The article writer should borrow it rather than invent one. The knowledge base is where the desk's voice is read most often and by the most people. An article that sounds like a different organisation from the ticket replies is an article the reader trusts less.

Three tones fail this reader reliably, and each is common. The lecture explains the policy, the history and the reasons before the fix. It tells the reader, in effect, that their problem is an opportunity to learn. They did not want one. The blame describes the problem as something the reader did. Examples are "users frequently forget to sign out", "this occurs when the password is entered incorrectly", and "ensure you have followed the correct procedure". The reader did not forget anything that they know of. Being told so by a page is a reliable way to turn a stuck user into an angry one. And the cheer tries to jolly the reader along: "Oops! Don't panic! We've all been there! Let's get you sorted!" A reader with a customer at the counter does not want to be told not to panic by a web page. The exclamation marks read as the page laughing. (Nobody in the history of locked-out users has been consoled by an exclamation mark.)

Write instead as the technician would speak on a good day: "This usually clears in a minute. Sign out at the top right, then sign in again. If that does not work, the steps below take about five minutes." No apology, because the article did not break anything; no reassurance beyond the time it will take; no reference to the reader's state at all. What a desk says when a moment is genuinely hard, when the fix is hours away or the news is bad, is the subject of Tone in Hard Moments. An article about an outage borrows from it. For the ordinary stuck reader, calm and plain is the whole of the technique. It is harder to write than it reads, because the writer's instinct is to help, and helping sounds like talking.

Tell Them What the Fix Will Cost

The frustrated reader is deciding whether to invest in the article. The article should tell them the bill up front: how long, what they will lose, and whether they can do it now. "This takes about two minutes and does not close anything else you have open" is a sentence that lets a reader with three minutes start. "This restarts the laptop; save your work first, and allow five minutes" lets a reader with a presentation in four minutes decide to call instead. That is the right decision. They have made it in ten seconds rather than at step 6 with the laptop already restarting. The writer knows the cost of every step. The reader has to be told.

Say what the reader will lose, every time there is a loss. That includes unsaved work, the current form, the items in the cart, the draft message, and the place in the queue. If a step discards anything, the step says so before the action, not after. In that case, the article's "before you start" says so at the top. A reader who loses twenty minutes of work to a step that said "click Restart" without warning will never trust the knowledge base again. They will be right not to. The cost of a warning is one clause. The cost of its absence is one reader, permanently.

Where the full fix cannot be done now, offer the way to get through the next hour. "If you cannot restart now, you can print from the shared desktop by the printer until you can." The workaround for the next hour is often the single most valuable line in the article for the reader with a customer waiting. It is almost always left out, because the writer is thinking about fixing the problem and the reader is thinking about the customer. The customer is right there. The fix can wait an hour. The article should know that.

When the Fix Is Not Theirs to Make

Some articles are about a problem the reader cannot fix: an outage, a known fault awaiting a supplier, a system that is down for maintenance. The frustrated reader of this article needs three things in the first three lines. They need to know that the problem is known, that they need do nothing to report it, and how to get by in the meantime. "The expenses system is showing 'service unavailable' for everyone this morning. The desk knows and is working on it; you do not need to raise a ticket. Claims due today can be e-mailed to the finance mailbox and will be entered when the system is back." Three sentences, and a reader who was about to raise the fortieth ticket about it has instead gone back to work.

Say when they will hear more, and keep to it. "This page will be updated by 11:00" is a promise the article can make even when nobody knows when the fix will land. That is because it promises an update, not a repair. A page that said "we are working on it" at 09:00 and still says it at 15:00 with no change is a page the reader stops believing. Once they stop believing the outage page they start phoning. The known-error article, with its workaround and its running count of affected people, is covered in Known Errors and Workarounds. What belongs here is that the reader of it is frustrated too. Front-loading applies: known, no action needed, get by like this, next update at this time.

A Short War Story: The Route App at Bellweather Logistics

Bellweather Logistics pushed a security change to its drivers' route app over a weekend. On the Monday at 05:00 twenty-two drivers in the Northgate yard found the app asking for a password that it would not accept. The desk had published an article in advance, titled "Route App Security Update: What You Need to Know". It began with three paragraphs on why the change was being made, and continued with a description of the new password rules. It reached the fix, "sign out of the app, sign in with the new password you set last week, and wait for the sync to complete", in its ninth paragraph. That was below an illustration of a padlock. The article ended with "if you have any difficulties, contact your line manager", and the line managers started at eight. Kofi, the transport manager, found the fix by phoning the one driver who had read to paragraph nine. The yard moved at 05:42. By that time fourteen first-drop delivery windows had been missed, each carrying a penalty under the customer's contract. The desk's phone had logged nineteen unanswered calls. The rewrite put "The route app will not accept your password" in the title and the three-step fix in the first four lines, with the out-of-hours number beneath it. The padlock went. A fix in paragraph nine is a fix that does not exist at five in the morning.

The Frustrated-Reader Checklist

The checklist below is run on the finished draft, reading only what the frustrated reader reads. That means the title, the first three lines, the headings and the steps. Cover the paragraphs with your hand if it helps. If the article passes on those alone, it will serve the calm reader too; the reverse is not true. The second section is the tone pass. The quickest way to run it is to read the first screen aloud in the voice of someone with a customer waiting. Listen for the sentence that would make you hang up.

FRUSTRATED-READER CHECKLIST — RUN ON THE FIRST SCREEN ONLY
Article: ________________________________   Checked by: ________   Date: ________

WHAT THEY SEE FIRST
  [ ] The title contains the symptom in the reader's words or the exact error text.
  [ ] Line one confirms "you are in the right place if ______".
  [ ] The most common cause has a one-line fix before the full steps.
  [ ] Step 1 is visible without scrolling, on a laptop and on a phone.
  [ ] No paragraph of background, policy or history appears before step 1.
  [ ] The escape hatch appears near the top: a route and a time, not a department.
  [ ] The escape hatch appears again at the end, with "say which step went wrong".

THE COST
  [ ] How long the fix takes is stated before the steps.
  [ ] Anything the reader will lose (unsaved work, a restart, a sign-out) is stated
      before the step that causes it and again in "before you start".
  [ ] A way to get through the next hour is given if the fix cannot be done now.

TONE (read the first screen aloud)
  [ ] No explanation of why before the fix.
  [ ] No sentence that says or implies the reader caused it: no "users often",
      no "ensure you have", no "incorrectly".
  [ ] No exclamation marks, no "oops", no "don't worry", no "simply" or "just".
  [ ] No apology from the article; no reassurance beyond the time it will take.
  [ ] Sentences under twenty words on the first screen.

IF IT IS A PROBLEM THEY CANNOT FIX
  [ ] Line one says it is known and that no ticket is needed.
  [ ] Line two says how to get by meanwhile.
  [ ] Line three says when this page will next be updated, and the page is.

LAST
  [ ] Read only the title, first three lines, headings and steps: does the reader
      get out in under a minute in the common case?  [ ] yes  [ ] no: fix ________

The loans article at Bluewater was rewritten by Priya on the desk that afternoon, from the ticket Sam had raised, in eleven lines. The title became "Why does the loans system say 'Your session has expired'?" The first line said it clears in a minute. The sign-out step was step 1, and the out-of-hours number sat beneath it with the words "if you have a customer waiting". The paragraph about the lending process survived, under a heading called "Why this happens", at the bottom, where it has been read by almost nobody and bothered no one. Sam's branch has had the same message on four Mondays since. Nobody has phoned.

Frequently Asked Questions