Writing Technobabble

Beyond this Point, There be Technobabble
or: How to Write for Today’s PC Users

by Jerry Stern
PC Tech, www.pc410.com

Many years ago, a friend was grumbling about the things we did to configure our computers. It was mostly downloading programs that could do things with types of files that were newer than what the operating system knew about–this was in 1981, by the way, and the computers were not IBM compatible. Nothing has changed.

What he wanted, he explained, was a computer that was a true black box. In scientific methodology, a black box is basically a sealed object that does something to input and creates output. If it’s a flashlight, it eats batteries and produces light; we don’t care how. If it’s an electronic widget, it takes signals in and puts other signals out; it’s all very mysterious. If you put in sliced bread, and toast comes out, it’s a toaster. He didn’t want to understand that if you send an electrical current through a very thin Nichrome wire, you get increased resistance to power flow and some of the current is converted to heat; he was hungry, and wanted toast. Never, never explain it. Beyond this point, there is only technobabble.


So his ideal computer would be a black box. We wouldn’t open it and tinker with the cards and chips, and deliberately install fans of the wrong voltage so they’d run quiet. (Yeah, it was 1981.) We wouldn’t go into CompuServe and search for software. We wouldn’t go looking for all kinds of converter software so that we could move data files from the program that could read it to the program that we wanted to read it. None of that stuff. Just put in files, and do productive stuff.

Now, it’s over 30 years later, and there are two basic ways to look at what’s changed. We, the software industry and hardware gurus of the computing industry, see that nothing has changed except a few labels. We still spend time abusing, patching, downloading, converting, and tweaking, and not actually creating stuff with our computers. Our software clients, on the other hand, have black boxes now. Or they use them that way, which we should be helping with, but generally don’t.

Yes, the boxes are black, just as in the traditions of scientific endeavors. What goes on inside of them is a total mystery. And they put in random clicks on anything and everything that appears on their screens, and they get output that has no apparent relationship with what they clicked. They see some messages that aren’t in English, must be some sort of polyglot stuff with lots of clicks in it, and mostly 3-letter words in all CAPs, and they know what that means–click on the “Go Away” button–that’s the big one. The message had stuff in it, but nothing memorable.

This is apparently perfectly logical to many computer users. They click something that says “Click here to install (something something, technobabble mystical-acronym)”, and hocus-pocus, up comes a magical new program that announces that it is dumb-loading and installing something for you that will fix the 521 new (something) holes, or was it detected bacteria, that it found in your monitor. Right, a new computer consists of a glass thing with pictures on it–that’s the CPU, or “Color Picture Unit”, and the box on the floor–that’s the big thing on the floor that the cat sleeps next to, because it blows warm air on her back. Sometimes it’s called that “thing I can mess up if I touch the wires”.

Now inside these boxes, there’s apparently something that stores smoke, something that makes a whizzing noise, and the clicky-clicky thing. These are all extremely dangerous items on their own, but if you leave them alone, nothing scary will happen. No, really. The best way to handle those things is to not get near them.

So, software developers, there you have the typical home user of computers, and quite a lot of business users, too. If you’re writing software for a non-expert, there are a few things you have to keep in mind when you put messages on a screen, in the help file, or on a web page:

1) Don’t use TLA’s

TLA means Three-Letter-Acronyms, but also don’t use longer acronyms. Abbreviations in general should be removed from your messages. KISS applies. That’s an acronym for “Keep It Simple, Stupid” and don’t use that one, either.

Acronyms imply previous knowledge in a specialized field, so don’t assume your customers understand any acronyms. After all, do you really want to explain that a picture program can work with a “TWAIN” device? No one will take your software seriously after you explain that it really is “Technology Without An Interesting Name.”

2) Don’t be FBC

Resist the temptation to keep your messages Fully-Buzzword Compliant. Putting in this year’s buzzwords is cool, it’s hip, or whatever this year’s word for groovy is, and sometimes those words prove that your software can work with the newest gadgets. And they date it as obsolete twelve months later. Save it for your keywords list and features specifications, and leave it off the screen and out of the “Getting Started” section of the help file.

Buzzwords, like acronyms, require prior knowledge in a specialized field. Yours, not theirs. Leave it out.

3) Don’t Write in Passive Voice

You can write in the first-person style, as in “I wrote this.” Or use the third person, like “Spot runs fast.” And the second person style would be “Next, you should click on the OK button.” And finally, there’s the omnipotent mystery person, who doesn’t exist. Writing teachers like to call that Passive Voice, where the subject of the sentence is unknown, and the action is described, but not assigned to anyone. They don’t like that–it’s the difference between “Teachers don’t like Passive Voice.” and “Passive Voice is frowned upon.” Always write in the Active Voice, they say. Well, why? Because when the sentence has no actor, and no one is doing the stuff in the sentence, you can’t picture it. If you can’t picture it, it’s harder to remember the steps you’re supposed follow in the instructions.

So how do you write in Active Voice, automatically? Use the second-person style for instructions. Tell the reader that “Next, you will select what color to use for your on-screen design.” That’s much clearer than reading the passive form: “Next, the color will be selected” and easier to maintain over a long explanation of steps.

4) Don’t Ask Questions

Software has to work on the first try or most computer users lose interest. Some will download something else. Others will ask that smart kid who shoveled the walk last Winter to fix their computer because you messed it up. So don’t ask any question that can be avoided.

For example, your software works with email. During the install, don’t ask which email software your user wants to work with. Just look in the system to see what’s installed as the standard mail reader, and configure for that choice. Yes, there can be an ‘advanced install’ button for the techies. For everything else, if there is any way to avoid a question, then don’t ask.

5) Don’t Pop Errors

Again, if you put a message on-screen, it will cause pain in some users, and the snow-shovel kid only knows how to configure Warcraft and iTunes, so if he’s shown an error, he’s going to show his nice neighbor who bakes cookies how to search for desert recipes. So there should never be an avoidable error message.

For example, your program works with graphics. The user clicks on Open, File, and clicks a file format that is normally not opened, but imported into the program. Software for a techie can pop an error, suggesting that the sequence should be File, New, and then File, Import. That’s not for a mass audience–instead, just switch to Import silently, and do what has to be done.

In other words, if you can make your software understand the most-likely user errors, and auto-correct for them, your customers will be happy that what they wanted happened, and you won’t have another tech-support answer to write. So auto-fix all random input–your goal is for the program to run properly even if the customer left the computer, after putting a small Capuchin Monkey, or maybe a smart cat, onto her office chair, and saying “Now don’t touch my keyboard, sweetie!”

Not All Software is for Dummies

Right about now, I’m hearing, “My customers aren’t dummies.” Yes, I hear that because the most-important skill in writing articles, or in writing software instructions, is to internally picture your audience in your mind as you write. Anticipate objections, and picture a skill level. Don’t try to write a program without understanding the audience you’re going to sell to–the result is a mixture of styles, and confusing.

For a mass-market program, try picturing your customers as experts on a topic that doesn’t have anything to do with your software. OK, they’re rocket scientists trying to learn a music program. Accountants trying to use a drawing program. Lawyers trying to create web pages. Cookie bakers trying to send email. And write your instructions as if they’re sitting at the computer listening as you explain how to make your software pop out what they really asked for: toast.

And no, they aren’t dummies. They do, however, own a few books in the “For Dummies” series by Wiley Publishing ( www.dummies.com ). They know something– write for easy reading, write without assuming background knowledge, write as if every reader is completely new to the book topic, and you’ll sell stuff. It’s a pretty good model to follow–there are over 1,800 books in the series. So far.

Jerry Stern is the editor of ASPects, the ASP’s Coordinator of Anti-Spyware Operations, does malware cleanups and hardware repair work for non-dummies at PC410.com and is online at www.sciencetranslations.com.