Blog Archives

What do technical writers do?

It’s a question often asked of us: “What does a technical writer do?”

We tell people how to do technically complex things, mostly by writing instructions but also by drawing pictures and making movies.

Want to know more? I’m impressed by the write-up in the Occupational Outlook Handbook, 2010-11 Edition, from the US Bureau of Labor Statistics.

Thank you Tom Johnson for tweeting the link to the handbook today!

Collective noun for a group of technical writers

This week a colleague, Tom, came up to me with a big grin and asked, “What’s the collective noun for a group of technical writers?”

He had another developer in tow, a new starter at that, and the grin made me wonder what mischief lay behind the question. πŸ˜‰ But it’s a goody and it made me laugh. I came up with “a scribble of technical writers“. Later, it occurred to me that we could call a group of agile technical writers a “jot“.

Can you think of any good names for us and for what happens when we get together in a group?

Technical writers do Atlassian FedEx Day

Every three months or so, Atlassians go mad. The frenzy lasts 24 hours, and it’s called “FedEx Day”. Up to now, the insanity has affected predominantly the developers. This time the tech writers went bonkers too. I survived to tell the tale, just barely. Here it is.

What is FedEx Day?

Atlassian is the software-development company I work for. FedEx Day lasts from 2pm on a Thursday to 2pm the next day. In those 24 hours, you get to develop anything you like. At 3pm on Friday, the presentations start. You get 3 minutes to present your project to the rest of the company. It’s called FedEx Day because your project must be delivered overnight. The winning project is decided by vote.

It’s a pretty cool idea. You get to try something that you wouldn’t normally do in your day-to-day job. The result just may turn out useful for you, your colleagues and the company. It often does. Some FedEx projects end up as part of Confluence, JIRA or another product.

For the most part, it’s the developers who go nuts. But three FedExes ago, a technical writer won the vote for best FedEx project! That was Ed, our team lead, who wrote a Flash game called Atlassian Invaders.

How did I do?

My report is a mixed bag of nuts. The first part of my FedEx was great. It was so much fun, spending a work day experimenting with something new. I played with some cool technology and managed to get some nice results. I’ll write another blog post soon, about the project itself. Here’s a tantaliser: my project is called,

Atlassian WTF πŸ˜‰

The second part was the presentation. I was really nervous about that, right from the start. And with good cause, as it turns out. FedEx Day presentations are notorious for going wrong. Mine did. The first time I tried it, my demo stopped working each time I plugged the projector cable into the PC. Thank you FedEx gremlin!

Matt, the FedEx Day coordinator, was kind enough to let me have a 2nd attempt. I started up the demo software first, then plugged in the projector.Β  This worked better, but I ran into more problems later in the demo. And I turned into a wobbly jelly, something I’m apt to do. Ah well, at least I was able to demo the general idea. I needed a good stiff Coca Cola after that!

What about the other technical writers?

They were right there, in the middle of the madness. Giles converted a Confluence user macro (the {expand} macro) into a macro plugin. That’s pretty awesome. Alas, the FedEx gremlin attacked him too. His macro refused to work for his presentation. He later discovered it was because the demo machine was running Safari, while he had been testing in Firefox.

Andrew wrote a specification for automating some of our Confluence documentation release procedures. We’re hoping this will be a useful tactic in persuading a developer to write the code. We’ve offered a chocolate bribe too. Is our optimism all part of the general madness? Watch this space πŸ˜‰

Rosie started writing some sample Confluence content that non-technical evaluators can download and import into their Confluence installation. She tackled a sample intranet site and a documentation space.

Ed created a Flash game, where old-school die-hard anti-code-review developers battle it out against reviewers encroaching upon their code.

It was great to see the varied, interesting and valuable FedEx Day projects the technical writers up with. Go tech writers πŸ™‚

The story in pictures

Friday morning, 5 and a half hours to go. Here are a few manic developers, with evidence of a hard night’s work in the foreground:

Technical writers do Atlassian FedEx DayTechnical writers do Atlassian FedEx Day

Technical writers do Atlassian FedEx Day

It finally happened. We’re going slightly mad. This FedEx Day was the first time that all the technical writers took part. Ed and Giles had done it before, but the rest of us were FedEx virgins. Here we all are, with other cross-product team members, all going just very slightly mad:

Technical writers do Atlassian FedEx Day

Technical writers do Atlassian FedEx Day

Half an hour left. The pace is frantic now:

Technical writers do Atlassian FedEx Day

Technical writers do Atlassian FedEx Day

Only too soon, the presentations start. We’re one wave short of a shipwreck:

Technical writers do Atlassian FedEx Day

Technical writers do Atlassian FedEx Day

We’re simply not in the pink, my dear:

Technical writers do Atlassian FedEx Day

Technical writers do Atlassian FedEx Day

There are more photos on Flickr. FedEx Day is fun. The presentation part of it is… nuff said. Maybe better next time. I think I’m a banana tree, and I’ll be there πŸ˜‰

Decomposing the Handbook for the Recently Deceased (from the movie Beetlejuice)

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

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:

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.
Decomposing the Handbook for the Recently Deceased

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?

A smooth ride through the text

Part of our job as technical writers is to give our readers a smooth ride through the text. And it’s not a small part of the job either. It’s important, even if it means we spend a fair bit of time correcting other people’s writing. Or does that just turn us into glorified copy editors — what do you think?

This isn’t new to most tech writers, but it came to mind again recently when I was making a couple of very small corrections to a page in our Confluence documentation. A reader had added a comment to the page, saying that she had noticed a couple of typos. Thank you Rosie πŸ™‚ (The comment is still on the page at time of writing this blog post, but it will probably disappear in a couple of weeks.)

Rosie had picked up two spelling mistakes: “serch” and “mutliple”. I myself find the second one particularly bothersome, because my eyes don’t quite believe that they’re seeing it right. So they go back a couple of times just to check that the mistake really is a mistake.

Why is this important?

Because we don’t want to distract our readers from the important stuff just because it’s written funny πŸ˜‰

OK, so prove it!

It’s easy enough when we’re talking about simple spelling mistakes. “Serch” should obviously be “search”. And “mutliple” is just painful. But what about the more complex aspects of grammar, vocabulary and style?

When you read a sentence like this:

Sarah is eat a chocolate.

you’re hit by a LAN.

And this one:

On the way to work this morning I saw a goldfish swimming around the bus.

gives you an N400 when you read the word “bus”.

A “LAN” (Left Anterior Negativity) is a measurable blip in the electrical impulse which your brain emits when your internal language processor encounters something ungrammatical — like the word “eat” in the first sentence. The blip takes between three and seven tenths of a second to register on an EEG.

An “N400” blip happens when you encounter a word which doesn’t fit the context – like the word “bus” above. This one takes about four tenths of a second.

This information comes from Steven Pinker’s book, Words and Rules. It was pretty cool to learn that there’s a measurable physical manifestation of that feeling of discomfort I get when a sentence jars.

But what is “correct” English anyway?

I might suffer a LAN zap when you write “Remember to invite Peter and I to your party”. But many people don’t!

(BTW, “Peter and I” is wrong in that sentence, and I’m ready to battle that one out to the end if anyone’s game to take me on πŸ˜‰ )

Or you might get a LAN buzz when I start a sentence with the word “or”. But I think it’s OK.

Why does the tech writer get to decide what’s right and what’s not?

We don’t. Language is a living, changing thing. Different words and constructs will sound good or bad to different people and at different times in history. Consistency is the key. Provided a document or a documentation suite is consistent in its usage of grammar, style and vocabulary, the reader will get that fabled smooth ride.

So which standards do we use? It doesn’t matter all that much, provided you pick a standard that is recognised in your neck of the woods.

At Atlassian, where I work, we use these two guides:

  • Style manual for authors, editors and printers (John Wiley & Sons Australia)
  • Macquarie Dictionary, Fourth Edition of the Essential Dictionary (University of Sydney)

We’re based in Australia. Our US office has copies of these books too, and we’ve agreed to go with the Australian standard because we’re originally an Ozzie company. I suspect that many Americans think it’s cute πŸ™‚

Taking standardisation even further…

Scott from DMN writes about a DocTrain West session he attended, given by Berry Braster and listing the advantages of Simplified Technical English.

A Scribbly Gum tree in my garden

Moving on to scribbles and smoothness of another sort… The Scribbly Gum tree is quite common in this part of Australia. It has a lovely smooth white bark which gleams silver in the wet.

A smooth ride through the text

A smooth ride through the text

As you get closer, you notice some weird zigzag lines marring the smooth surface. It’s just as if someone has scribbled on the bark.

A smooth ride through the text

A smooth ride through the text

The markings can be quite intricate and almost seem have some meaning which you can’t quite discern.

A smooth ride through the text

A smooth ride through the text

But actually, the “drawings” are tunnels dug by theΒ larvae of the Scribbly Bark moth, known less intimately as Ogmograptis scribula.

A smooth ride through the text

A smooth ride through the text

I vote that we make the Scribbly Gum the mascot of technical writers. All in favour say “aye” πŸ™‚

%d bloggers like this: