ffeathers — a technical writer’s blog

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?

Imagine if you could use a wiki’s editing and collaboration tools to create your documentation, and then export your complete documentation set to a recognised XML format such as DocBook or DITA. From the XML, you could use your existing tools to transform the documentation to the various formats required by your different audiences or put it through your normal publication and archival workflow.

K15t & Friends are working on the Scroll Wiki Exporter, which exports Confluence wiki spaces and pages to DocBook and PDF. I’ve tried the beta DR03 version of the product and I think it has a lot of potential.

A friendly note of warning: The Scroll Wiki Exporter is currently in beta release. It is a Confluence plugin, developed by a third party. It is not part of the core Atlassian Confluence product. If you want to try it out, you should install the plugin into a test installation of Confluence.

Scroll Wiki Exporter is a Confluence plugin that converts a set of wiki pages to DocBook or PDF. You can choose to export an entire space or any page tree (hierarchical set of documents) within a space.

Screenshot after installation of the beta plugin, showing the Scroll Wiki Exporter option in the Confluence Tools menu and Scroll’s Export Options page:

What can it do right now?

The software is in an early beta phase, so there are still some limitations on what it can do. The Scroll development team are adding new capabilities with each new beta release.

Scroll Wiki Exporter converts Confluence wiki spaces and pages to DocBook and PDF. Confluence itself supports a number of formatting options and macros. When you run Scroll Wiki Exporter, it analyses the wiki pages and displays warnings of any formatting it will not be able to reproduce. You can choose to ignore the warnings and do the export anyway. The beta version is best used with Confluence 2.8.2. The Scroll team will be working on compatibility with other versions for a future release.

For those participating in the beta testing, the Scroll team have provided some excellent documentation. It is clear and well structured, simple and to the point.

The documentation is itself written on Confluence and then converted to PDF using Scroll Wiki Exporter. It is also provided as the sample content (i.e. a Confluence space) for beta testers to use when testing the software. Multi-purpose documentation at its best There are a few grammatical errors, but basically the team have provided a very solid guide to getting Scroll Wiki Exporter up and running.

I’ve used the Scroll Wiki Exporter to generate PDF and DocBook outputs, using the sample space provided with the beta documentation. The DocBook output passes XML validation, and the PDF output looks good. I have also tried the Scroll Wiki Exporter with the Crowd documentation space, but there were a few hiccups because of the formatting and macros used in that space.

Some interesting aspects

Scroll Wiki Exporter allows you to choose a theme for your generated PDF or XML. The beta version I tried has only the default and Scroll themes. But the idea is that you will be able to add your own themes, defined in FOP (Formatting Objects Processor).

You can also choose to export a whole space, or a page tree starting from a selected page. At the moment, Scroll Wiki Exporter hooks into Confluence’s own page tree functionality. So when you re-arrange pages in the tree, you are actually re-arranging them in the Confluence space too. In a future release, there will be an independent means of organising pages just for the export.

Because I don’t use DocBook in my day-to-day documentation procedures, it was not easy to put the generated XML through its paces. It would be great if other technical writers can try it out too.

Scroll’s plans for the future

The Scroll team intend to provide conversion to DITA in a future release. At the moment, they are refining the DocBook capabilities. Once the framework is well established, they say, it will not be difficult to produce other formats such as DITA.

Calling tech writers

As someone who is enthusiastic about technical documentation on a wiki, I think the Scroll Wiki Exporter is a great initiative. The ability to export Confluence documents to a recognised XML format is a much-requested feature. See the existing requests for DocBook (CONF-762) and DITA (CONF-5571) support. This requirement also comes up often in forums, interviews and technical documentation conferences.

Technical writers may want to keep an eye on this one. The Scroll team will be issuing a public beta release within the next couple of months. Especially if you are already using DocBook in your day-to-day documentation procedures, your feedback would be really useful to the Scroll team. Let’s jump in there and give them as much feedback as we can. And I’d be very interested in your comments too:)

In August last year, I planted two trees at about the same time as I started this blog. Now the trees and this blog are just over a year old. A good opportunity for some stats

ffeathers

WordPress says that ffeathers has:

• 62 posts
• 184 comments
• 184 tags (hmm, interesting but meaningless coincidence)
• 17,216 total views
• 7,584 blocked spam comments (thank you Akismet)

The most popular post is The agile technical writer with 1,247 views.

Today, someone found ffeathers by Googling for:

“your mouse has moved” error

I hope you found what you were looking for

Prickly Paperbark

Yesterday, another person came here searching for:

paperbark tree information on growth

So in your honour, here’s some idea of what a Paperbark tree does in a year.

The Prickly Paperbark was a tube, about 40cm high, when I planted it in August last year. Now it’s nearly 2 metres high and quite robust. (It needs to be robust, to survive the onslaught of weeds, floods, cold and heat that our garden inflicts upon it.)

Prickly Paperbark a year ago, at 40cm

Prickly Paperbark now, at 198cm

It has a very pretty trunk and bark already. The diameter of the trunk is almost 3cm at its thickest part.

Prickly Paperbark close-up

Old Man Banksia

The Banksia has not grown much since I last measured it in April this year. It’s approximately one metre tall, and battling an ever-changing environment. Since I planted it, a couple of tree ferns have muscled in on the territory.

Old Man Banksia last year, at 17cm

Old Man Banksia now, at approx 1 metre

Still, it is putting up a gallant fight. Its trunk is almost 2cm in diameter and it always has a lot of new growth, although much of it goes sideways in an attempt to find the sun.

Old Man Banksia close-up

As well as my two favourites, we planted around 20 native trees and shrubs last year. Spring has sprung, and we’ll be shopping for more soon. Death to all agapanthus