Reading technical documentation is nobody’s idea of an enjoyable night in. You could try to make it special with some wine and candlelight, but it’s still going to be a stretch. Therefore, the documentation needs to strike that balance between being complete while using as few words as possible. If you use too many words, no one will want to wade through it to find the information; if you use too few words, the information won’t be complete or useful.

Flexing your Vocabulary

One of the ways to strike that balance is shorten sentences by using strong verbs, descriptive nouns, and common language. While the written word and spoken language are two different beasts, you can often simplify words and sentences by asking yourself “If I were explaining this to someone, is this the word I would use? Who speaks this way nowadays?”

For example,

BAD: “In order to reduce obscurification, one must employ the appropriate level of verbiage that targets the desired balance of plenitude while being spartan in the use of colloquialisms.” (I almost fell asleep in the middle of writing that sentence.)

BETTER: “To ensure written clarity, you need to strike a balance between being complete and using a minimum of words.”

BETTER: “Make sure that your writing is clear and complete by picking your words carefully, crafting your sentences to be short and strong, and remove any language that drags.”

TOO MUCH: “To be clear, don’t use too many words.” — This tells the reader what to do, but not how to do it.

Reduce your Phrasing

While trying to sound literary the way Ms. Crabapple always insisted, writers sometimes pad their sentences with too many introductory words. More words do not make you look smarter: being smart and mindful when using strong, snappy words make your sentences come alive.

The following are some common phrases that I’ve seen that can be reduced easily, making for stronger, punchier writing:

In order to run: To run

Whenever you want to run: To run

It may be desirable to run: You may need to run

In order to utilize your running shoes: To use your running shoes

Please select the following running shoes: Select the following running shoes
(I know it seems rude, but never politely beg the user to following the instructions)

A large number of people run: Many people run

Passive Voice

When possible, try to avoid using the Passive Voice. In the Passive Voice, the subject that is performing the action is unclear, so you end up with long sentences that jump around to avoid naming anyone specific. You can get around this by speaking to the reader directly using the 2nd person voice (You).

BAD: “The required information is acquired upon successful application of sufficient force to the button.”

BETTER: “To get the information you need, press the button.” BETTER: “To get the information, you should press the button.” BETTER: “To get the information, press the button.”

There are times when using the Passive Voice is unavoidable. Therefore, it should be used sparingly. Er, I mean… *you* should use the Passive Voice sparingly.

So I have been having to sit on this for about a week, but now I’m allowed to show it off. Here’s the story.

In mid-December, I was contacted by an office furniture-design company in the Montreal area called Group Focus (groupefocus.com) who asked me to write a script for them for a promotional video. They were going to a conference and were asked to put together a promo video for their company.

For this video, they decided they wanted to focus on their people rather than their products/services, and they wanted to go with a wolf/nature theme. I wrote them a script, they loved it, I did the narration, they still loved it, and here’s the final product.

I was looking up some stories and I came across this Islamic folktale:
–
The following is an incident about an engine failure in a giant ship. The ship’s owners tried one expert after another, but none of them could figure but how to fix the engine. Then they brought in an old man who had been fixing ships since he was a youngster. He carried a large bag of tools with him, and when he arrived, he immediately went to work. He inspected the engine very carefully, top to bottom.

Two of the ship’s owners were there, watching this man, hoping he would know what to do. After looking things over, the old man reached into his bag and pulled out a small hammer. He gently tapped something. Instantly, the engine lurched into life He carefully put his hammer away. The engine was fixed! A week later, the owners received a bill from the old man for ten thousand dollars.

“What?!” the owners exclaimed. “He hardly did anything!”

So they wrote the old man a note saying, “Please send us an itemized bill.”

The man sent a bill that read:

Tapping with a hammer $ 2.00
Knowing where to tap $ 9998.00

Effort is important, but knowing where to make an effort in your life makes all the difference.

When you are working with people, either as a co-worker or as a manager, and you have someone explaining something to you that either you don’t understand or you think is outlandish, you need to hide these emotions from your body language.

Not that you need to just accept whatever people are telling you. Sometimes people are confused, inexperienced, or just plain wrong. You can still work with these people and either get them on your page, on your side, or they might have insight you have not yet considered.

But when they are explaining it to you, be careful what you are broadcasting. If they see something in your body language that tells them that you think they are stupid or a waste of your time, they may not want to work with you anymore, or they may actively work against you.

Years ago (in the mid-1990′s I think), I was doing a contract for a client that developed their own touch-screen technology for the food service industry. I had submitted a draft of the documentation for review to a client with a one-week turn-around. A week later, I sat in the client’s meeting with the heads of various departments and prepared to receive their comments.

Project Lead: I didn’t have time to review it, so I gave it to the head of Marketing.

Marketing Lead: Reviewing the Guide wasn’t really our job, so we gave it to the head of QA.

QA Lead: We didn’t have time to review it, so we gave it to the programmer.

Programmer: I’m too busy with coding to be reading the Guide, so I gave it to the Project Leader.

Embarrassed, the Project Leader turned to me and said “We’re very sorry for wasting your time. Charge us for the whole day and give us another week.”

One week later, I returned to their meeting room and all the same people were there, except they looked really angry. Apprehensively, I awaited their feedback.

Project Lead: I’ve been hearing horrible things about this Guide, so I’m going to let Marketing have their first crack at listing the problems.

Marketing: Reviewing the Guide is *still* not our job, so I don’t know why you even asked us again! We gave it to QA because finding bugs is their job!

QA Lead: Our job is to test the application, not find typos! We’re already overloaded without having to read the Guide! We gave it to the programmer. He’s the one who should know if the Guide is correct or not!

Programmer: This Guide is useless and a piece of crap!

Project Lead: So you did review it this time?

Programmer: Well… no. But I showed it to my mother and she *hated* it.

Horrified, the Project Lead said “I’m very, very sorry to waste your time again. Charge us for the day and I’ll have comments for you by the end of the week, you have my word.” As I walked out, the programmer was getting his head taken off by all the department heads. I finished up the project that month and they were quite satisfied with the work.

A couple of months later, I was paying for my meal at a restaurant when I noticed the cashier was having trouble punching it in. I gave her some advice on how to punch in the order, and when it worked, she looked at me incredulously and asked “How did you know that?”

I reach to the side of the cash register and pulled out the client-printed User Guide and stated “Because I wrote this!”

Just in case any of you go crazy and decide to be Technical Writers, let me impart this nugget of wisdom: when writing instructions, be aware that users PRESS keys on a keyboard and they CLICK buttons on the interface. These terms are NOT interchangeable.

Also, the SCREEN is the piece of hardware you use to see the application, but the application itself appears in a WINDOW. These terms are also NOT interchangeable.

Does no one remember what happens when you cross the streams? Bad things happen. BAD. BAD. THINGS.

I submitted a sample draft of a User Guide to my client a few days ago and I got the feedback today. Most of it was fine, but this one comment made my left eye twitch:

Is there a way to reduce text and replace it by illustration like ikea user guide? I think it would be much efficient.

I don’t think using Ikea as the model is a good idea. Ikea has a reputation for having completely illegible and confusing picture-based instructions.

They say that a picture is worth 1000 words, and in certain cases, that’s very true. For example, this is true for art when each person can have their own interpretation of a piece of art and come up with their own 1000 words to describe it and have it be perfectly valid (if not, it’s at least open for debate).

But when it comes to technical instructions, each reader must come up with the same, precise 1000 words to successfully complete a task. This is the beauty of words because they are precise and specific, unlike a picture which is always open to the randomness of interpretation.

Words: good. Words and Pictures: better. Pictures alone: risky. A friend pointed me to this great illustration at Retronaut: