Say It in the Air

Sentences can be unruly things, particularly when they attempt to describe technical content. By the time you wedge in all the disclaimers and conditions, you often have cobbled together enough convoluted clauses to make a native speaker cry.

The procedure will ensure that the user still have access to the recorded video prior to the removal of the devices.  Typical use case is when IP addresses on the devices need to be changed (not officially supported feature) and the customer is not willing to lose access to the previously recorded video.

I’ve read this three times and I still don’t know what it means. In addition to the stilted sentence structure, words like “prior to” are dead giveaways that this author is trying to “write”, where “writing” is some strange, alien activity that must be labored through. For many subject matter experts, it is. That’s why tech writers have jobs.

Were I to encounter the example paragraph in a work situation (which, in fact, I did), my favorite method is to simply ask the developer what his procedure is meant to accomplish. At first, he might try to speak in “writing”. “Prior to replacing, to preserve the IDs, one must perform …”

At this point I tend to gently interrupt and say, “No, just tell me. What are you trying to do?”

Usually he’ll then answer in plain English. “You need to save the device IDs before you replace the equipment, or the user will lose access to the files recorded by the old equipment.”

What a nice sentence! Short and to the point. Now everyone knows what this procedure is about, without having to decipher the written “tech speak.”

The beauty of the “just say it” technique is that it works on your own sentences. If you find yourself picking up clauses and dropping them here and there, trying to disentangle a misbehaving sentence—just sit back, take a breath, and tell yourself, out loud, what needs to occur, just as if you were explaining it to someone else in person. Chances are you’ll come up with two simple, direct sentences instead of a long, convoluted one. And no one will have to diagram the sentence to figure out what it means.

Posted in Blog, Tech 101 Tagged with:

Leave a Reply

Your email address will not be published. Required fields are marked *