Let Monty Python help you build techcomm lists correctly

Monty Python offers a most entertaining reminder about the safest way to introduce bullet lists in their sketch The Spanish Inquisition:

Omit the number of elements in the list’s introduction. This allows you to add elements to the list without having a wrong introduction.

In the words of Cardinal Ximénez (Michael Palin):

NOBODY expects the Spanish Inquisition!

Our chief weapon is surprise…surprise and fear…fear and surprise….

Our two weapons are fear and surprise…and ruthless efficiency….

Our three weapons are fear, surprise, and ruthless efficiency…and an almost fanatical devotion to the Pope….

Our four…no…

Amongst our weapons…. Amongst our weaponry…are such elements as fear, surprise….

I’ll come in again.

Imagine what Ximenez’s diatribe looks like in Word with changes tracked:

Two Three Four Cchief weapons of the Spanish inquisition:

• Surprise Fear
• Fear Surprise
• Ruthless efficiency
• An almost fanatical devotion to the pope

It’s only a small problem, but time and again, I’ve been caught with a list in my documentation of “the following five countries/languages/currencies” – followed by seven elements, including two which had been added later.

Bonus fun fact

According to the sketch’s Wikipedia entry, the catch phrase “Nobody expects the Spanish Inquisition” spawned several more occurrences in pop culture, including a headline “in 2004, when the Abbey National bank was to be sold to the Banco Santander Central Hispano: ‘Nobody expects the Spanish acquisition!'”. 🙂

Advertisement

Writing to create context to think – and work

The skill of technical communication is to create a context in which other people can work. – This concise insight helps me to stay focused on my users and their tasks, even if it’s not totally original.

I came to it via an article by Tim O’Reilly in his Financial Times article “Birth of the global mind” where he quoted Edwin Schlossberg:

The skill of writing is to create a context in which other people can think.

 

Favorite tech writing dogmas

I’m usually wary of dogmas, but some just won’t go away, they assert their eternal truth in uncanny ways. I’ve recently found some new ones, so I now have four five tech writing dogmas:

1. A new tool will not fix broken processes.
2. No matter how cool you are as a software company, don’t build your own help tool – it’s not worth it.
3. Don’t invent yet another universal standard. – from xkcd’s How Standards Proliferate
4. Following a style guide will not make you a good tech writer (unless you understand methods and processes such as topic-based authoring and single sourcing as well) – from Scriptorium’s The latest style for tech comm: adding value
5. “No matter how much you try, you can’t stop people from sticking beans up their nose.” (This metaphor can apply to customers who use your documentation or to non-documentation managers who make decisions about documentation.) – from Jared Spool’s highly entertaining and insightful post

Your turn

What do you think: Are these some of the eternal truths in the world of tech writing? Have you encountered them? Or are dogmas inherently silly and evil? Please leave a comment.

What’s in a (serial) comma?

An example of a missing serial comma got tweeted my way which was too good to be true:

Among those interviewed were his two ex-wives, Kris Kristofferson and Robert Duvall.

And here’s the guy who was married to both, Kris and Robert… 🙂

How to wash George Harrison’s car

This is from 1962 when George Harrison was trying to break into tech writing, playing guitar on the side. He’s not bad for a 19-year old. To wit:

• He presents the procedure step by step.
• He uses the imperative for clear instructions – though he lapses into conditional “should”s occasionally.
• He speaks to his reader’s needs and allows her to interrupt the procedure for a cup of tea – twice!

So the world lost a promising tech writer – but gained a wonderfully imaginative guitarist. Well done, George! And thank you for the music.

Managing: Instruction vs. communication

I’ve found an enlightening opposition in Jurgen Appelo’s presentation “The Dolt’s Guide to Self-Organization“, slides 54-55:

Managing a lifeless system is all about instruction.
Managing a living system is all about communication.

What struck me was that we tech writers often consider task-based instructions in documentation already better than feature-based system description.

But seen from a managing perspective, Jurgen reminded me once again that instructions are at best an intermediary step on the way to a good user experience.

How advertising is the opposite of documentation

You know that documentation and advertising are at odds, if you’ve worked in either for any length of time. Here’s a conspicuous definition of advertising that’s pretty much the opposite of what documentation does:

I want to make the public aware of something they don’t quite yet know that they know – or have them feel that way. Because they’ll move on that, do you understand? They’ll think they thought of it first. It’s about transferring information, but at the same time about a certain lack of specificity.

I found this in chapter 7 of William Gibson’s novel Pattern Recognition. Last I heard, the book hadn’t yet become one of the seminal texts in advertising, so take it with a grain of salt… 🙂

The dangers of PowerPoint

Every time you make a PowerPoint, Edward Tufte kills a kitten. – Mark Goetz

I picked this up as a ‘re-re-re-tweet’, and the original sleeper post from last November called “My new wallpaper” has a cool wallpaper design worthy to go onto a geeky t-shirt!

Oh, and here’s a blog post “Dilbert on PowerPoint Presentations” which collects 24 strips on the topic.

Getting sequences right

The M*A*S*H episode “The Army-Navy Game” illustrates the importance of getting sequences right in technical writing. Blake and Trapper John are trying to defuse a bomb:

LT. COL. HENRY BLAKE (reading instructions)
And carefully cut the wires leading to the clockwork fuse at the head.

TRAPPER JOHN (cuts the wires)

LT. COL. HENRY BLAKE
But first, remove the fuse.

The rights of the reader

Some lighter fare today from Daniel Pennac. The French novelist formulated “10 Rights of the Reader”, plus one warning. They are aimed at readers and writers of fiction, but no doubt readers of documentation take several of these liberties, too:

2. The right to skip.
3. The right not to finish a book.
8. The right to dip in.

Find all of the rights on a cool poster by illustrator Quentin Blake, available as a PDF from Walker Books. For more about the “bill of reader’s rights”, check out the review in the British Guardian.