Skip to content
jalogisch

count to three, not five - write instructions for the one who throws

· development

In support I write for very different people. Every day. One wants it running again, now. The next one wants to understand why the cluster did what it did, down to the last detail. Same product, sometimes even the same problem. A completely different answer.

The best explanation for this I know does not come from a book about technical writing. It comes from Monty Python.

the holy hand grenade

In “Monty Python and the Holy Grail” (1975), King Arthur and the knights stand in front of a killer rabbit. Brother Maynard brings the solution: the Holy Hand Grenade of Antioch. And of course the instructions. A monk reads them from the Book of Armaments, chapter two, verses nine to twenty-one.

First comes a long blessing, with lambs and sloths and carp and anchovies and orangutans and breakfast cereals and fruit bats. Brother Maynard cannot take it anymore: “Skip a bit, Brother.” Then the real part. Count to three. Not four. Two only if you go on to three. Five is out.

Five rules for one number, and most of them tell you what not to do. Then the king pulls the pin and counts: one, two, five. Galahad: “Three, sir!” Arthur: “Three!” Throw. Boom.

If you have done support for some years, you know this scene. You just never had the fruit bats.

what is wrong with these instructions

Everything important is in there. That is the problem.

The text is written for the one who wrote it: their ritual, their liturgy, their completeness. Not for the one who has to throw. The one thing you must do comes last, after everything nobody asked for. “Skip a bit” is what every reader of a long ticket answer thinks, they are just too polite to say it. There are more rules about what not to do than about what to do. And nobody tested it with a real user under pressure. In front of Arthur there is a rabbit, not a reading lamp.

So when the user counts to five, do not blame the user. Who blames the user for counting to five has never stood in front of the rabbit.

why we write like this

There is a name for it: the curse of knowledge. In 1990, Elizabeth Newton at Stanford let people tap well-known songs on a table, and other people had to guess the song. The tappers expected about half of the songs to be guessed. Reportedly it was 2.5 percent. The tapper hears the melody in their head. The listener hears knocking.

When I write a support answer, I hear the melody. I know the product, the logs, the history of the bug. The customer hears knocking.

how I try to do it

I have to find out what the customer wants, and nobody tells me directly. So I look at what and how they ask, what they send with their question, and how they react to my answers. If somebody answers only one of my three questions, my next answer gets shorter and more precise. If somebody sends a very precise question with a lot of details, I mirror that and go deep.

And I have to be honest: I explain too much more often than too little. I want people to leave smarter than they came, so they do not come back next month with the same problem. So yes, sometimes I am the monk with the long reading.

That is fine, as long as the throw comes first. My answers start with what is needed right now: do this, then it works. tl;dr. After that comes the why, for everybody who wants it. It is the Book of Armaments turned upside down: count to three, throw, and then the liturgy for those who like liturgy.

If you want a framework for this, have a look at Diátaxis. It splits documentation into tutorials, how-to guides, reference and explanation, depending on what the reader needs in that moment. Arthur needs a how-to. The monks read an explanation. Both are fine. Just not in the same breath, and not in the wrong order.

galahad

My favourite person in this scene is not Arthur and not the monk. It is Galahad, who does not write any instructions, but stands next to the user and says the right number at the right moment.

That is support. Good documentation is great. But sometimes the best documentation is somebody who says “Three, sir!” before it goes boom.

PS: If you think nobody in tech takes this seriously enough: in 2018 somebody submitted an Internet-Draft called “The Holy Hand Grenade of Antioch” to the IETF, author “Arthur son of Uther Pendragon”. It is expired and has no standing. But it exists.

Read more: curse of knowledge, Diátaxis, Google Technical Writing: audience.