When I saw the film Beetlejuice recently, it struck me that a technical writer must have played a big part in, and had a lot of fun with, the scenes involving the Handbook for the Recently Deceased. So let’s pay tribute to this unsung hero, this spectral tech writer extraordinaire.
Image from the film Beetlejuice.
Technical writing is often accused of being deadly 😉 dull. Is there a grain of truth in that, and how can we liven it up a bit?
A rewarding task for trainee technical writers could be to analyse the Handbook for the Recently Deceased. You could even concoct a useful interview question when you’re looking to hire a technical writer:
Have you seen the film Beetlejuice?
Tell us what was wrong with the Handbook for the Recently Deceased.
If the interviewee isn’t flummoxed, they’re bound to be a useful technical writer, or at least crazy enough to be one.
In the spirit 😉 of simplicity
Simplicity, clarity and structure are of grave 😉 concern to technical writers. If our readers are to have the ghost of a chance of understanding our documents, we need to take care with every word.
Two other bloggers are dead right when they say:
- “The clean style of choosing the shortest words and clearest sentence forms makes a refreshing change to many documents.” (From my colleague Matt, in his post A small victory for plain English.)
- “Users turn to the help to look for a specific question, just as someone consults an encyclopedia for a specific question.” (From Tom Johnson, in his post Users Read Help Manuals Like an Encyclopedia, Not a Novel.)
Task 1: Analysing the Handbook
In the film Beetlejuice, when Barbara and Adam first see the the Handbook for the Recently Deceased, Barbara says, “You know what? I don’t think we survived the crash.”
[So it seems that’s one thing the Handbook got right. The title gave them a clue about their current state. But wait. Adam misreads the title as “Handbook for the Recently Diseased.” The title could use simpler words and give more of a hint about the sort of information the book contains.]
Now Adam is reading while Barbara is pacing up and down, chewing her nails and looking very worried. She says, “I hate this. Just… Can you give me the basics?”
[There’s no Quick Start Guide.]
Adam replies, “This book isn’t arranged that way. What do you want to know?”
[The structure of the book doesn’t help these poor lost souls find the information they need.]
Barbara shoots a volley of questions. “Well, why did you disappear when you stepped off the porch? Are we half way to heaven or half way to hell? And how long is this going to last?”
[Hey tech writer, an FAQ section would be helpful. There are some other obvious candidates here: Where am I? What am I? Where are all the other dead people?]
Adam goes on, “I don’t see anything about heaven or hell. This book reads like stereo instructions. Listen to this:
Geographical and temporal perimeters: Functional parameters vary from manifestation to manifestation.
[That’s as clear as mud! Know your reader and use simple language, or at least define your terms up front, so that Barbara and Adam know that they are “manifestations” now.]
Understandably, Barbara and Adam are a bit dispirited. Still, they keep trying. Adam keeps paging through the book, and Barbara carries it around with her.
[Everyone knows the value of documentation.]
At last our heroes’ perseverance starts paying off. A family of living people moves into Barbara and Adam’s house and start re-building it. Our heroes dislike the new inhabitants and hate what they’re doing to their home. Barbara says, “What are we going to do?”
Adam says, “We’re not completely helpless, Barbara. I’ve been reading that book and there’s a word for people in our situation. Ghosts!” He grins with triumph.
[Go, tech writer, go. The book is coming into its own at last. It is giving the reader some useful terminology, and correctly targeting its audience.]
But it’s a painfully slow learning task. Barbara and Adam try some hair-raising (literally) tricks, but in vain, because the living can’t see them. Meanwhile, re-construction of the house is steaming ahead and chaos is merrily ensuing. They gaze out of the attic window, still clutching the book. Barbara says, “Isn’t there an index or something?”
[Yes, where is the index?]
At last, just when things are at their worst, Adam remembers something. “We need some help. I read something in this book this morning:
Emergencies: In case of emergency, draw a door.”
[A trouble-shooting section comes in handy.]
Barbara is by now totally disillusioned. “‘Draw a door’? I don’t know why we keep looking in that stupid book!”
But Adam picks up a piece of chalk and draws the shape of a door on the wall. Nothing happens. He looks in the book again, and finds more instructions. “Aha! Knock three times!”
[Step-by-step instructions, clearly demarcated in a block of text, would have worked wonders here.]
Adam knocks three times on the wall and a door opens, leading them into a weird way-station. But alas, all is not yet sweetness and light. They find a desk marked “Information”. But they don’t have an appointment, because they didn’t know they needed one nor how to make one.
[The Handbook should have a section on contacts and support.]
There’s more. Watch the film 🙂
Task 2: Rewriting the Handbook
Now let’s ask our trainee technical writer to describe how they would go about re-writing the Handbook. First, they would map out a new structure for the book and create a skeleton document. I’ll leave the rest to your imagination.
Drawing by Ryan.
For those haunted by a grammatical niggle
Did you wonder, when you saw the title of this blog post, whether “decompose” is a transitive verb? If you did, then:
(a) you’re (well on the way to being) a technical writer, and
(b) you’ll be delighted to know that it is. I looked it up in the Concise Oxford English Dictionary.
How many truly ghastly puns did you stumble across when reading this post? If you found close to ten of them, or even all eleven, then:
(a) you have a morbid fascination with death, or
(b) you have a morbid fascination with puns, or
(c) you’re (well on the way to being) a technical writer 🙂
Any more technical writers in literature or film?
Zen and the Art of Motor Cycle Maintenance, by Robert M Pirsig, could be called a handbook for technical writers, and much more. Does anyone know of any other technical writers or technical writing in literature and film?