Best Tech Writing Tip Ever: Watch a User Try to Follow Your Instructions

What we sometimes assume (left) versus the reality (right)I once read an essay by Joseph Epstein in which he describes the glee and suspense in watching a stranger read his essay. It has 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.

Madcap FlareAdobe Robohelp

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm interested in topics related to technical writing, such as visual communication, API documentation, information architecture, web publishing, JavaScript, front-end design, content strategy, Jekyll, and more. Feel free to contact me with any questions.

  • Pingback: WritingNiche» Thoughts on writing()

  • Pingback: The Recruiting Animal()

  • Pingback: slapjack()

  • Pingback: Beveiligde Weblog Login «

  • Pingback: My Notes - links to downloadable academic papers, journals, news, information()

  • Janet

    Funny, and not surprising. I think most people just want to use software, not understand it, so they mess with it until they get stuck and then read the instructions. Good post. :)

  • John

    I think you should read about Minimalism (John M Carroll), which demonstrates how tool users learn more quickly and thoroughly by trial and error than they do by following complicated processes.

    Carroll proved that users with flash cards learned better than users with user guides.

  • Alan J. Porter

    In my days as a Tech Pubs Manager at a large engineering company I managed to persuade the guys on the assembly line for one day to put aside the engineering drawings and use the manuals to assemble the product. We learned more about what needed fixing in our publications in that one day than in six months of internal desk top reviews.

    Ever since then I’ve always been a strong believer in that the best way to QA your documentation is to give it to someone who has no knowledge of your product and ask them to use it to install and do a few simple tasks.

  • roGER

    Great post!

    I believe we can also go beyond our strict job-definition as writers and hopefully have the interface designer(s) either present, or able to view the video tape afterwards!

    It also helps to encourage the ‘student’ to speak their current thoughts out loud – at best in a kind of ‘stream of consciousness’ type of monologue.

    A rather bitter 15 year old memory still bothers me – showing the results of a trial with a person new to a system to a senior project manager. His glib answer was “oh, our users are smart and won’t react like that.”

    It’s an attitude I’ve often recalled when struggling with some new piece of technology myself…

  • CabSav

    Great point, Tom. Sitting with someone while they read your instructions can be a humbling experience.
    I was also interested Alan Porter’s, “persuad(ing) the guys on the assembly line for one day to put aside the engineering drawings and use the manuals”. A picture is worth a thousand words they say. The most popular piece of documentation I have written in the last 12 months is a simple graphic with the fields users have to fill in highlighted, with appropriate choices from the drop-down lists. People actually use it.

  • Tom

    John, thanks for the recommendation on minimalism. I’ll check out your link.

    roGER, I like the idea of a webcam recording the user. It would be less intrusive, and the user couldn’t fall back on the tech writer for explanations.

    CabSav, thanks for your thoughts. My most popular documentation is the short, visual guides too.

    Alan, thanks for sharing your experience and insights.

  • avi

    I found out that the more I get familiar with the product I document, the worse the documentation becomes. Things that look trivial to me are not so for novice users.
    Dumbing-down the text – shortening yet simplifying it – is always welcome.

  • Pingback: Technical Writer » Archives » Even if the documentation is good, you still only read the bits you need to()

  • Pingback: When Writing Tips, Think Of The User -

  • kim nathans

    I tried this at my last job after attending a WritersUA conference. I was really impressed with the session on creating a usability lab and watching the user for “points of pain.” I had our receptionist follow a walkthrough I’d written on creating a basic report with our product. She was happy to do it, so she’d better understand our products, and provided me with invaluable feedback. I too was dismayed at the scantiness of the attention she paid to my carefully crafted words. One invaluable action item I walked away with: show context in screen shots. I was saving myself future maintenance tasks by providing tiny screen shots of individual icons or buttons, but when I saw how hard she had to work to find those UI items in the UI, I revised this practice immediately. Now, if the UI item is near the top right, I make sure that I include the X for a point of reference. No matter what, I always try to include something big in every screen shot as a point of reference as I picture Jane peering back and forth, back and forth, straining to find that tiny icon.

  • Pingback: StumbleUpon » Your page is now on StumbleUpon!()

  • Pingback: » When Writing Tips, Think Of The User()

  • Pingback: links for 2007-08-11 « Costi’s evansmemo()

  • Pingback: When Writing Tips, Think Of The User()

  • Pingback: Watch Users Read Your Writing()

  • Pingback: Recruiting Writing For Blogs()

  • Pingback: Bad Language / Five cool links about writing()

  • Pingback: 译言翻译 - 译言人的发现()

  • Pingback: Google Scraper()

  • Dumoulin Hystan

    This is very interesting information. Bookmarked.

  • Pingback: Skins Develop Madcap Flare - Dogpile Web Search()

  • Pingback: 10 Ways to Gather Feedback from Users | I'd Rather Be Writing - Tom Johnson()

  • Pingback: 有關教學文的一些思考 : M’s漫無章法()

  • Pingback: Remember the reader : Rebecca Thomas Designs()

  • Pingback: New series: User-centered documentation | I'd Rather Be Writing()