Why Technical Explanations Fail, and the Question They Miss

Thursday, 10:20, at Tollgate Foods. Priya in payroll has walked over to the desk because the payslip run has to go out by noon and "the e-mails aren't going". Marcus looks at the mail server, finds the cause in four minutes, and tells her: "The relay is deferring outbound because the SPF record for the new domain hasn't propagated yet, so the receiving side is greylisting us." Priya says "Right." She waits a moment, then asks the only question she has: "So should I send them again?" Marcus has just given a correct, complete explanation to a person who now knows one more thing than before. Something called SPF has happened to her.

An explanation, for the purposes of this article, is anything a technician says or writes to a non-technical person about why something broke, what was done, or what will happen. It succeeds when the listener can act on it and repeat it to a colleague. It fails when they leave with a nod and no more ability than they arrived with. It fails this way far more often than it fails by being wrong. This article is part of our Explaining Technical Things to Non-Technical People series. This article is about the failing, because you cannot fix a habit you have not seen.

It covers why an explanation is measured at the listener's end and not the speaker's. Then come the five ways explanations fail: the curse of knowledge, jargon, too much detail, the wrong level, and answering the question you wish they had asked. Next come the one question every listener is actually asking and how to spot a failed explanation before the person leaves. The article ends with a short war story and the explanation pre-check to copy, in that order.

An Explanation Is Measured at the Listener's End

The technician grades the explanation by whether it was true. The listener grades it by whether they can now do something. These are different tests. An explanation can get full marks on the first and nothing on the second. That is exactly what happened to Priya. Nothing Marcus said was wrong. Nothing he said was usable either, and usable is the only mark that counts outside the desk.

This is uncomfortable because it moves the responsibility. If the explanation was correct and the listener did not understand, the natural conclusion is that the listener needs to try harder. That natural conclusion is wrong. The listener is not being tested; the explanation is. A plumber who tells you the problem is "a failed compression joint upstream of the isolation valve" has told you the truth and left you standing in a wet kitchen. You would not say you had failed to understand plumbing. You would say they had not told you whether to turn the water off.

It helps to remember what the listener brought to the conversation. Priya brought a deadline, a payslip run, and a worry that she had broken something. She did not bring a model of how e-mail is delivered, and she does not need one to do her job well. The desk's job is to add the one thing she lacks, which is what to do now, not to replace her picture of the world with the technician's. Most failed explanations are an attempt to do the second thing in the time available for the first.

Failure One: The Curse of Knowledge

The curse of knowledge is the difficulty of imagining not knowing something you know. Once you understand how a password reset works, you cannot easily remember what the words "the account is locked" sounded like before you understood them. So you use them as if they were plain English. They are plain English to you. To the requester, "locked" might mean the laptop, the door, or something they did wrong, and the one word has carried three different worries across the desk.

It is a curse rather than a mistake because it does not feel like anything from the inside. A technician under the curse is not being lazy or arrogant. They are speaking the way they think. The way they think is now full of structure the listener does not have. The more expert you are, the worse it gets, because more of your vocabulary has quietly become technical without anyone telling you. I have caught myself telling someone they "just need to clear the cache" and realising, from their face, that they were wondering where on their desk the cache was kept.

The test for the curse is to ask what the listener would have to already know for your sentence to be useful. "The SPF record hasn't propagated" requires knowing what a record is and what SPF does. SPF is Sender Policy Framework, a published list of the servers allowed to send a domain's e-mail. The sentence also requires knowing what propagation means for e-mail. Those are three things, none of which Priya has, and the sentence is therefore addressed to a different person. Nobody can lift the curse; you can only check for it, every time, which is what the pre-check at the end of this article is for.

Failure Two: Jargon Doing the Talking

Jargon is the vocabulary a trade uses among itself, and it fails the listener in a particular way: it sounds like an answer. "It's a DNS issue" has the shape of an explanation, with a subject, a diagnosis and a confident full stop. So the listener nods, because nodding is what one does at an answer. They have received a sound. The sound has been accepted. Nothing has moved between the two heads. DNS, the Domain Name System, is the address book computers use to find each other by name. It remains as mysterious as it was.

Jargon is also where the curse of knowledge hides most comfortably, because every jargon word is one you forgot was jargon. "Server", "sync", "the network", "permissions", "the cloud", "a patch", "the backend": each is ordinary speech on the desk and a closed door off it. The dangerous ones are the words that also exist in ordinary English with a different meaning. A "domain" is a kingdom, a "host" throws parties, and a "handshake" is what you did when you met the new finance director. The listener hears the ordinary word and builds the wrong picture with it.

The fix is not to stop knowing the words. It is to decide, each time, whether the word or the thing it stands for is what the listener needs. Usually it is the thing. "The address book that computers use to find each other had an old entry for the file server" is longer than "DNS issue" and contains everything Priya's colleague in accounts would need. The substitutions, and the rule for when to say the technical term once anyway, are the subject of Skipping the Jargon Without Dumbing It Down. This article only needs you to notice that a word did the talking and the listener did the nodding.

Failure Three: Too Much Detail

Too much detail is the failure of the conscientious. The technician knows the whole chain of cause and effect. It runs from the failed update to the service that did not restart to the share that was unreachable to the spreadsheet that would not open. They give the listener the whole chain, in order, because leaving any link out feels like hiding something. The listener wanted the last link. By the time it arrives they have stopped listening, somewhere around the service that did not restart, because none of it was about them.

Detail fails because the listener cannot tell which parts matter. To the technician, the chain has a shape: this caused that, that caused the other. To the listener it is a list of unfamiliar events of equal weight, and the one that matters to them, "your spreadsheet will open now", is buried fourth. A long explanation also carries an unspoken message: the problem was complicated and might not really be fixed. The listener leaves more worried than they came. The technician meant it as reassurance. Six causes in a row is not reassuring to anyone.

The honest reason for the detail is often that the technician is explaining it to themselves, out loud, with the requester standing in for a colleague. That is a reasonable thing to need and the wrong place to do it. Put the chain in the internal note on the ticket, where the next technician will be grateful for it. Give the requester the link that concerns them. If you run QuerySolv, the ticket already keeps the public reply and the internal note apart. That makes the split a matter of which box you type into rather than a discipline you have to remember. In any tool, the note is for the chain and the reply is for the person.

Failure Four: The Wrong Level

The level of an explanation is how much the listener is assumed to know. There is no correct level, only the right one for this listener. The same fact about the same outage needs four different sentences. The listeners include a fellow technician, a confident power user, and the requester who raised the ticket. The last is the manager who wants to know whether to warn the board. Pitch it too high and you get the nod. Pitch it too low and you get something worse: a competent adult being told that "the computer got confused", which they will remember long after the outage.

Pitching too low is the failure people forget to worry about. The desk is so often warned about jargon that it over-corrects, and the explanation becomes a children's story with the facts removed. The person who runs the payroll for four hundred people is not a child. She can hold "the mail server was refusing to send until a setting was fixed" perfectly well. She will resent "the e-mail had a little hiccup" for the rest of the year. Dumbing down is not kindness; it is a different way of not telling someone what happened.

The table below shows one fact at four levels, so you can see the levels as choices rather than as talent. The fact is that a shared drive was unreachable for forty minutes because a server restarted after a failed update. Every row is true. Only one is right for any given listener, and the listener, not the fact, decides which.

Finding the level is a question, not a guess. "How much do you want to know about why?" takes two seconds. Most people answer it honestly: "Just tell me if my files are okay" or "Actually, I'd like to understand it." Asking also pays the listener a compliment, because it treats the level as their choice rather than your estimate of them. (The estimate is usually wrong, in both directions, and nobody has ever complained about being asked.)

Failure Five: Answering the Question You Wish They Had Asked

The last failure is the subtlest, because the explanation is correct, plain, and brief, and still misses. The requester asks "when will it be working?" and the technician answers "it broke because the certificate expired." That is the answer to "why did it break?", which is the question technicians find interesting and would have asked themselves. It is not the question that was put. The requester now knows why, still does not know when, and has learned that asking the desk a question gets them a different one answered.

Technicians drift to the "why" question because it is where their skill lives. Diagnosing the cause was the hard part of the ticket and the satisfying part, and explaining it is a way of showing the work. The requester did not see the work and did not ask to. Their questions are nearly always about time, effect and action: when, what does this do to me, what should I do. "Why" comes a distant fourth, and it is usually asked out of politeness, or to make sure it was not their fault.

The fix is to answer the question that was asked first, in one sentence, and then offer the one you wanted to answer. "It should be working by two o'clock. If you'd like to know what happened, it was a security certificate that expired overnight." The second sentence is now a gift rather than a substitution, and the requester can decline it. Most will. The ones who accept it were going to ask anyway, and they will understand it better for having had their own question settled first.

The Listener's Real Question

Under every question a requester asks there is one question, and it is "what does this mean for me?" The person asking "is it fixed?" means "can I do my work?" The person asking "what happened?" usually means "was it me, and will it happen again?" The person asking "how long?" means "do I need to tell my manager, cancel the meeting, or find another way?" A technical explanation succeeds when it answers that underlying question, whatever words the surface question used. It fails whenever it answers a different one, however well.

This is why the three-part shape works: what happened, what it means for you, what happens next. The middle part is the real question answered in so many words, and the other two give it a cause and a future. The shape is set out with worked examples in The Three-Sentence Explanation. What requesters want to hear while they wait is in What Users Actually Want to Know. For this article the point is narrower: every one of the five failures is a way of not answering "what does this mean for me?" Checking for that one question catches all five.

The test is to read your explanation back and ask where the listener appears in it. "The relay is deferring outbound because the SPF record hasn't propagated" has no listener in it at all. It is a sentence about servers. "Your payslips are stuck in a queue and will go out automatically within the hour; you don't need to resend them" is a sentence about Priya. It would have ended the conversation at 10:21. An explanation with nobody in it is a diagnosis. It belongs on the ticket, not in the hallway.

Spotting a Failed Explanation Before It Leaves the Room

Failed explanations have tells, and they are easier to catch in the moment than to repair a week later. The first is the polite nod, with or without the word "right": the listener accepting a sound. The second is a pause followed by a question you have just answered, which means the answer did not arrive in a usable form. The third is the question about action, "so should I...", which means your explanation contained no action. The fourth is "okay, thanks" delivered a beat too quickly, which is a person leaving a conversation they have given up on.

When you see one, do not repeat the explanation louder or slower. Repetition at the same level is the same failure twice. Instead change the level or the question: "Let me put that differently: your e-mails are queued and will go on their own. Nothing to resend." Or ask what they will do next and listen to whether it matches what you meant. The ways to check understanding without turning it into a test are in Confirming They Understood Without a Quiz. The point here is only that the tells exist and that the moment to act on them is now, while the person is still at the desk.

In writing, the tells arrive later and cost more. A reply that was not understood produces a second ticket, a reopen, or a "sorry, what should I do?" message the next morning. Or it produces nothing at all, because the requester gave up and asked a colleague. Each of those is a failed explanation that has been given a ticket number. Reading your own reply as the requester before you send it, which is step six of the pre-check below, is cheaper than reading it as a reopen on Monday.

A Short War Story: The Certificate at Meridian Parts

Meridian Parts ran a small web shop for trade customers. One Monday its security certificate, the file that lets a browser trust a site, expired because the renewal reminder had gone to a mailbox nobody read. Dev, the technician on the desk, found the cause in ten minutes and e-mailed the sales manager, Carla: "The TLS cert on the storefront lapsed at midnight, the CA renewal didn't fire, I've reissued and I'm waiting on propagation." Carla did not know that TLS, Transport Layer Security, was the padlock in the browser. Nor did she know that the CA, the certificate authority, was the company that issues it. She read "lapsed" and took it to mean the site had been taken down for non-payment. She spent the morning phoning the finance director and two suppliers to find out what had not been paid. The site was back by 10:30. The phoning went on until lunch. The finance director lost two hours, and an account manager at a supplier was left thinking Meridian had a cash problem. Dev's e-mail had been accurate in every word. The lesson the desk took was that an explanation is not finished when it is correct. It is finished when the reader knows what it means for them. Dev's second draft, written that afternoon for the next time, began with "the website is back up and nothing was unpaid".

The Explanation Pre-Check

The pre-check is six questions to run against an explanation before you give it, spoken or written. It takes under a minute once it is habit. It does not write the explanation for you; it catches the five failures before the listener has to. Keep it next to the screen for the first month. After that you will hear the questions in your own voice while you type, which is the point.

EXPLANATION PRE-CHECK — RUN BEFORE YOU SEND OR SAY IT
Ticket: ________   Listener: ______________   Spoken [ ]  Written [ ]

1. WHO IS LISTENING
   [ ] I know what this person does and what they need to do next
   [ ] I have asked, or can tell, how much "why" they want
   Level chosen:  [ ] technician  [ ] power user  [ ] requester  [ ] manager

2. THE QUESTION THEY ASKED
   Their words: ___________________________________________________
   What they really want (time / effect / action / cause): __________
   [ ] My first sentence answers THEIR question, not mine

3. THE LISTENER IS IN IT
   [ ] The explanation says what this means for them, in their terms
   [ ] It says what they should do, or that they need do nothing

4. THE WORDS
   [ ] Every technical term is replaced with a plain one, or named
       once and explained beside it
   [ ] No word with a different everyday meaning is left unexplained

5. THE LENGTH
   [ ] One cause, not the chain (the chain goes in the internal note)
   [ ] Three sentences, or a reason why it needs more

6. THE CHECK
   [ ] I know what I will ask or watch for to see if it landed
   [ ] If written: I have read it once as the listener, not the author

If any box is empty, fix the explanation before it leaves the desk.

Run it on Marcus's first sentence and five boxes stay empty. The level was technician. The question answered was "why" when Priya asked "what do I do". Priya did not appear in the explanation. Three terms were unexplained, and there was no check. Run it on the version he gave her two minutes later, after she asked about resending, and every box fills: "Your payslips are safe and sitting in a queue on our server. They will go out on their own within the hour, so please don't resend them. I'll e-mail you when the last one has left." Same technician, same facts, same morning. The second version took longer to think and less time to say, which is the trade this whole series is about.

Frequently Asked Questions