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

Summing up Scriptorium’s tech comm experts webcast

In Scriptorium’s “Ask the experts” webcast on 17 April 2012, Sarah O’Keefe, Nicky Bleiel and Tony Self reflected on frequently asked questions and trends. Here’s a timed play-by-play synopsis, so you can access the bits in the recording that interest you.

I try to provide teasers, not spoilers, so scoot right over to Scriptorium’s blog and check out the meaty answers for yourself!

FAQs

The panel starts with the questions they hear most often, from the underlying architecture via the tools to the deliverables.

5:46 – What is the best help/XML/CMS tool to use?

Tony tackles this first question. While there is no clear, short answer, Tony sums up some criteria which can guide your choice to selecting a system that works for you.

9:20 & 14:20 – What should we be delivering?

Nicky hears this one frequently – and often the underlying sentiment is: “So many outputs, so little time.” Again, there’s no simple answer that suits everyone, but Nicky outlines how to make an appropriate decision. And once you throw single sourcing in the mix, you’ve likely got a scenario that works for you. (They go back to this question after the next one, that’s why there are two timestamps!)

11:54 – Should we implement DITA/XML?

Sarah has several answers for this question: Showing an ROI is tricky, but most compelling – and it is more likely in some scenarios than others. The strategic aspect of making your content future-proof helps, but it may not be sufficient for your business case.

Hot topics

Next up are some more or less controversial questions:

18:50 – Should we use a wiki for documentation?

The experts chime in with several perspectives that can help you make a decision. Tony thinks it can be a valid format for many use cases, Sarah cautions of the very different processes a wiki brings.

25:10 – Content strategy: Is it a fad or fab?

The experts’ answers focus on what content strategy actually means for technical communications, from “we’ve basically been doing it for years” to embracing it as part of our profession’s maturing process to new job roles and titles.

30:30 – The tech comm career: Is it awful or awesome?

This one is interesting: The experts see both, the glass half empty AND half full. The consensus is that the role for technical communicators is changing, and fast, so there are challenges and opportunities to those who adopt.

Audience participation time

For the last round, the webinar audience submits some questions for scrutiny:

37:50 – Can tech comm be complex when products get ever simpler?

The panel is not ready to dumb down documentation at all costs. Complexity may be warranted depending on the products and audience expectations.

42:15 – Is agile good or bad for tech comm?

Agile can be good for tech comm, when it’s implemented well. Tony also points out that agile may give technical communicators a stronger role in the development process.

45:55 – Can product specs be turned into docs with a single edit?

It’s hard to tell without knowing the details. But probably not.

Advice about breaking into tech comm

Some time ago, a lab technician asked me how to go about breaking into technical communications. I’ve already replied to J privately, but I thought the issue could be of interest to you as well, so here’s J’s question and my reply, both edited for publication.

J wrote me:

I’ve recently become very interested in the Technical Communication field. Currently, I’m working as a lab technician for laboratory machinery which can sometimes be very difficult to operate.

I’ve been spending more and more of my time poring through technical instructions, talking to sales associates, and transcribing everything into easy-to-understand instructions to be used by my co-workers. This has expanded to the point where I break down complex laboratory procedures, peer-reviewed studies, etc. into something my co-workers can understand.

I really enjoy this sort of work and would like to make a full time career out of it. But I don’t know where to begin.

Ideally, I’d like to begin by doing this sort of writing as a freelance gig and slowly build up my business until it affords me a comfortable living.

What’s the best way to get started? Do tech comm writers typically work freelance or are they typically full-time employees for a particular company? Can you recommend any websites or books that might help me out? How do most people in the Technical Communication field make their money?

And I replied:

Hi, J,

From what you tell me, you’re on a very good way to becoming a technical communicator, for two reasons:

You focus on users. In my experience, it’s essential to have the right perspective in that job: To understand the users and to make sure they can do their jobs well. Many tech writers get bogged down by the systems they describe and their features, because they’re right in their faces. Of course, knowing these is important – but your first obligation should be to your users. They are your customers, whether they are inside your company or outside.

You have strong domain knowledge. Many tech comm’ers either have a strong writing background (and a liberal arts degree, like I do in American Studies), or they have, loosely speaking, an engineering background. You’ll find your background valuable in 3 ways:

1. You’ll need it to get respect from your peers, whether you collect information from them or ask them to review your documents.
2. You’ll gain trust from your readers/customers, when they realize you speak their language and know what you’re talking about.
3. It will help you with managers who often appreciate domain knowledge over writing skills, if only because they think that “anybody can write”.

A general disclaimer before I go on: I’m afraid I don’t know the US job market nearly good enough to offer reliable advice. I’ve gone to school in the US, and know some tech comm’ers there, but I’ve never actually worked in the US. So I can’t really advise you on the freelance vs. employed question. My impression is that it seems to be pretty difficult to go the freelance route when you’re just starting out…

That said, there are really both scenarios:

• Self-employed tech comm’ers often appreciate setting their own rates and hours and the mix of topics they cover. But it’s difficult to build a customer base that keeps paying your rent.
• Employed tech comm’ers have a regular paycheck, but many complain about being awfully low on the corporate totem pole/food chain. Unless you establish good rapport and earn respect (which is hopfully easy for you thanks to the two reasons above), you might find that many colleagues and managers don’t really understand what you do, how you add value to the company.

Two books I’ve found especially helpful are:

• Developing Quality Technical Information is good and relevant, even though it’s 7 years old. It’s basically a gigantic, well-argued check list with lots of good examples. If you only were to read a single book on tech comm, I recommend this one.
• DITA Best Practices came out about half a year ago. This is a very good book if you publish any kind of online documentation, whether you follow the DITA standard or not. Chapters 1, 2, 3, 4, 7, and 10 are about topic-based authoring, specifically about designing, writing, linking and editing topics. It’s a very instructive hands-on book with lots of examples.

Online resources are plentiful, I recommend you start with:

• Tom Johnson’s blog I’d rather be writing. He’s the most visible tech comm blogger and has been helpful in the past, answering questions about breaking into tech writing. Lately, he’s opened up a few such requests to communal answers. If you don’t get a direct answer from him, I think you’ll find his past posts and their comments helpful. Plus, he’s based in the US!
• Social networks are nicely summed up and compared in Bill Albing’s post “How social can we go”. I like ATC and TWW.
• Twitter is also a massive hangout for tech comm people. These two lists are a good start to follow us around.

I hope I could give you some ideas and helpful advice. I wish you good luck in what I think is an exciting profession!

All the best, Kai.