Best Tech Writing Tip Ever

I once read an essay by Joseph Epstein in which he describes the glee and suspense in watching a stranger read his essay. It’s happened to many novelists too — the coincidental (dreamed-about) situation where you encounter a stranger reading page after page of your book, without realizing you’re present.

I had the opportunity to do somewhat the same today: to watch someone try to follow instructions in a guide I was writing. I learned more from the 20 minutes of watching than I would have learned checking over the guide and testing the instructions for 3 days myself.

Areas I thought were simple turned out to be a little confusing. The person hardly read the guide at all; instead, she glanced at it quickly while focusing most of her attention on the screen. When she did read, she read sloppily, in haste, sometimes reading the wrong section (she was often out of place in the sequence of steps). One time she lost track of where she was, and didn’t even look at the image where the correct area was circled.

Now granted, she knew I was watching. In fact, I asked if I could observe her following the guide. For the most part, she did follow the steps correctly. I was just surprised by the haste, the glancing and scanning instead of reading.

How-to guides are not pleasure-reading documents. Of course I know that. It’s not like creative writing, where you hope the reader savors the sentences, carefully and thoughtfully processes your ideas and smiles at your wit.

I learned several things from this twenty-minute observation:

> Graphics are important even if the buttons or selections on the interface seem obvious to you. The user scans and glances. What would normally require 5-10 seconds to read carefully, she reads in 2 seconds. The image helps her correlate the screen with the instructions. The image often serves as the main content she consumes rather than the words. What is obvious to you, the writer of the guide, may be obvious only out of familiarity — no doubt you’ve spent hours with the application, studying out every menu and function. So of course you know the Admin button is on the top right! But watch the user look with confusion at the interface, searching for it, though it’s right in front of her.

> Long paragraphs aren’t read. The user glances for 2 seconds at the guide for every 10 seconds or so she looks at the screen. Because of these glances, keep the sentences in your guide short and easy to follow. Abundant white space, graphics, lists, and bullets should be the norm in the guide.

> Be even more clear and apparent than you’re inclined to be. While your sentences may be clear and well-structured, simple, to the point, can you process the same information from a two-second glance? Dumb-down the instructions a little — more so than you think. Pretend you’re writing for a sixth grader rather than an adult. Not that the user isn’t intelligent, but the time she gives to your instructions may require increased simplicity to process it all at a glance.

> Your user is in a hurry. You may have written the instructions in patience, with calm demeanor, approaching each step and function with longsuffering determination to be exact and accurate. But the user is in a rush. She wants to finish the task as soon as possible. Doing this task is an interruption in her day. Your document is a nuisance. It is the last thing she wants to be doing or reading at the moment. The quicker it’s over, the better.

Of course users and situations vary. And the fact that I was present, available for explanations should the instructions or application prove too confusing, throws askew any scientific observations about user behavior. Still, watching a user try to follow the instructions I wrote was probably the single most effective way of evaluating the clarity, helpfulness, and worth of my instructions than any other method I’ve used.

It doesn’t take more than 20 minutes to an hour to get more feedback than you will ever have time to implement. I am now making this user-observation a standard — even if I have to bribe someone with chocolate or proofreading favors to do it.