Archive for the ‘humour’ Category
The Naked Tech Writer
Jamie Oliver’s reason for choosing the title “The Naked Chef” was that it implied simplicity. He wanted to convey the idea that simple recipes are best. Simplicity is something we technical writers strive for too. In choosing vocabulary and syntax for our technical documentation, we’re at least consistently good at dressing down, even if we don’t often go the full monty. So I think we can justifiably claim the sobriquet, “The Naked Tech Writer” 
You may remember my agile turtle, original and then re-engineered by Ryan. Here she is again, naked as the day she was drawn:
By Ryan
Tom Johnson has the topic of simplicity well covered. So I thought I’d look into the other possible interpretations of our new nickname, The Naked Tech Writer.
Out there on a wiki
“Naked” might mean “out in the open, for all to see”. If you are writing documentation on a public wiki, as I am, this rings very true.
“Every change you make, every page you break, they’ll be watching you.”
Readers add comments to the documentation pages, and they get to know you by the replies you give. We try to respond to most people’s comments. If necessary, we also update the documentation in response to their requests. Some time later, we remove the comments and our replies.
So while the documentation itself remains unadorned, devoid of personal style (as much as possible), the comments on the pages often do reflect the character of the technical writer. It can be rewarding to converse with your readers like this. Sometimes it’s just plain fun.
Here’s an example of a recent chain of comments on a page in the Confluence documentation. By the time you read this blog post, the comments may have disappeared, so I have taken some screenshots:
The Naked Tech Writer
The conversation got better and better. Here’s another screenshot, with the comments shrunk to show just the first few words of each:
The Naked Tech Writer
When was the last time you had that much fun with your clothes on?
Baring all in a blog
Quite a few technical writers are keen bloggers. Perhaps it gives us a chance to reveal the more showy side of ourselves. “You see, technical writers do have dress sense after all.” It’s difficult to make documentation look sexy, though some people do manage. But you can dress your blog to the nines.
Dispelling the myth via a photo album
Technical writers are coming out all over the show. Have you seen the photo gallery published by Cherryleaf? “I’m a Technical Writer — Dispelling the Myth”. My team is on page 13. Are you in there too?
I’d be sorry to go back under cover
Sometimes people email me directly, such as when their question relates specifically to their own environment or when it’s “big” question about processes and procedures, rather than something which relates to a specific page of the documentation.
I enjoy this kind of direct contact with the readers. Their comments enrich the documentation. Often I need to go and do some extra research to find the answer to a question. That makes it even more rewarding when I can give the person the answer, and of course update the documentation if necessary.
There are a couple of things on the downside of having such a visible profile. It’s time-consuming, responding to comments on the documentation pages and answering emails personally. At first it was even a bit disconcerting to receive direct emails. But right from the very beginning, even in the first few days of starting work on the wiki, I loved it.
A while ago I received an email from Shirley, who was watching the entire Atlassian Confluence documentation wiki. Such dedication! One day she noticed a large number of page-changes flash past her RSS feed, all with the same time stamp. It looked as if I had changed many pages all at the same time, and she wanted to know what the magic was. She ended her email with:
“And I hope this provides you with a good laugh!”
I explained that I had changed a page name and Confluence had automatically updated all the hyperlinks from other pages throughout the wiki.
And it did give us both a good laugh.
If I ever go back to a less “naked” form of technical writing, I will miss the exposure the wiki gives.
Other ways of undressing
The Naked Tech Writer is here, and here to stay. I’m sure there’s a lot more fun to be had with this nickname. Let me know if you think of any other ways a technical writer gets nekkid. And thank you in advance to WordPress and Akismet for the reams of spam they will undoubtedly trap on this blog post!
Hello, is that you?
Today I walked past two women just as they saw each other on a street corner. This is the snippet of conversation I overheard:
A: Hello!
B: Hello, is that you?
A: Yes.
They both thought this was a perfectly sensible exchange, but I had to chuckle as I went out of earshot.
Why can’t our documentation be as directly and succinctly understood? Because we don’t know the subtext for every passerby who comes across one of our pages.
The title of this blog post has a double meaning, because I am writing it from my iPhone while sitting on the bus. Yes, it’s me.
Say it like it is
Clarity is everything, in signs as well as in technical writing.
This sign doesn’t pull any punches I guess you could call it the Manly Council version of “Life, the Universe and Everything”:
Say it like it is
Transcription (with adapted capitalisation and punctuation):
MANLY COUNCIL
Beware. Unstable rock formation. KEEP OUT. If you choose to proceed beyond the fence there is risk of serious injury through collapsing rock including but not limited to serious neck and spinal injuries and even death. By Order, General Manager.
“Serious injury… including but not limited to… death.” Oh dear.
And I particularly like the last bit: “By Order, General Manager”. It adds just the right touch of bathos.
Decomposing the Handbook for the Recently Deceased
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.
Decomposing the Handbook for the Recently Deceased
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?
Uh, yes.
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?
Heart of documentation
Documentation answers all the big questions of life: How did I get here? What’s it all about? How do I do it? What’s next?
This leads to the inescapable conclusion that documentation is at the centre of the life, the universe and everything.
Even if all it says is: ‘Wrong way — go back’.
