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!'”. 🙂


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.

Instructions for everything

If Ikea Made Instructions for Everything” is a brilliant spoof on (almost) wordless IKEA instructions by the folks over at CollegeHumor.

This made the rounds a few weeks ago on social networks. If you didn’t catch it then or want to revisit it, check it out now. I especially like the “Hädrönn Cjollidder”… 🙂

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.

Not having way…

“Some people have a way with words….some people….not have way.”
Steve Martin in Born Standing Up: A Comic’s Life