Blog Sponsors

• 3Rabbitz book
• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

I say it should have been a day of celebration. Instead, it was an event I knew was out of date. The client flipped through the manual, glancing. He then set it down and we talked about reviewing schedules, because no one felt the client would actually read the manual on his own. Yes, we had to nail down a schedule and force him to choke it down in weekly bites.

In truth, I dislike delivering “the manual.”

In “Move over DITA – Chaos Is Coming!,” Alan Porter suggests that rigid structural writing, such as DITA, is at odds with the looser, more chaotic social media so prevalent among the younger generation. Rather than trying to force-fit the DITA standard onto our documentation, he says we might instead “step back and look at how [our] kids do their homework. Because in five to ten years they will be [our] new workforce, and perhaps more importantly, [our] new customers.”

In other words, we should rethink our documentation model. Rather than a rigid structure, we might consider following the pattern of how people actually access and use information today.

Exactly how do kids do homework these days? Alan says his daughter uses a variety of social media applications — wikis, social networks, instant messenger, folksonomies, social bookmarking. Observing his daughter complete her homework, he writes,

The first thing she did was google “Pearl Harbor” and started visiting links. First stop was Wikipedia. Then she got on Facebook and YahooIM and started using messaging to ask friends who were online for recommendations. These friends were literally from all around the world, so she was given access to resources that gave totally different perspectives than those given in the classroom. …One friend suggested going to a social bookmarking site and searching using a variety of user applied tags. Instead of taxonomy she was now applying folksonomy.

In a recent IT Author podcast, Alistair Christie interviews his daughter about how she uses computers, and his daughter explains that she never uses the help, because it’s almost impossible to find what you’re looking for. Instead she learns by simply using the interface, clicking buttons, looking at labels, and asking others for help if she needs it. The world of traditional help deliverables — long manuals with table of contents and indexes, expandable books in online help, even video tutorials — these all seem last resorts in user’s mind.

I don’t use the DITA model, but I do use standard topic-based authoring methodology, single-sourcing between online help and a printed PDF. Reading Alan’s post and listening to Alistair’s podcast, as well as hearing the feedback I always hear about help –- “I try to learn the application on my own first, and only turn to the help when I’m stuck” –- makes me think the old-school paradigms of help (the manual and the online help) are falling by the wayside. They aren’t harnessing the latest social media technologies. They aren’t appealing formats.

Alan also observes a sad truth:

For most of my working life to date, the technology I used at work far outpaced that I used outside of work.

But not any more.

Now the technology I use at home has generally outpaced that found in most workplaces.

This is the tragedy of technical communication. Rather than embracing and leveraging the latest web technologies, tech comm is stuck in the early 1990′s, delivering the same old content that no one wants and few can make sense of.

Blog Sponsors

• 3Rabbitz book
• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

Although I practice the latter (adding explanatory text before the steps), I recently read an article by Mike Hughes that convinced me readers rarely read text that appears before a numbered list.

Here’s the gist of Mike’s article. He’s really talking about on-screen text, but I’m extrapolating the principle to apply it to my online help.

When using an application, users are motivated to take action, and their focus is easily drawn to action objects such as menus, buttons, and text fields.

Once an action object or other visual element on a page has drawn a user’s focus downstream in the focus flow, it is difficult to redirect it back upstream. In other words, if something initially draws a user’s attention to the middle of a page, it is far more likely that the user will continue across and down as opposed to going back up the page. This is especially true if there are additional action objects downstream.

See “Instructional Text in the User Interface: Some Counterintuitive Implications of User Behaviors” for the full article.

Two weeks after reading the article, it still rattles around in my mind. I think just like a button on a page, users are drawn to a numbered list. Although I still add some “why” or “when” before my numbered lists, if the information is critical, I insert it somewhere in the list.

Here’s an example.

Embedding important information where readers will see it

The information about why you’d want to make a spinach shake precedes the numbered steps. But the critical information about using frozen peaches is embedded in the list because readers would most likely skip over it in the introduction.

Thanks for a great article Mike. By the way, Mike’s blog is here.

And if you want to read more about Shrek shakes, see Jane’s post: “Shrek Shakes and Twinkies.” We went through a 3 week period at our house where we drank nothing but Shrek shakes. Then one day my oldest daughter said she was sick of them, and we all agreed and haven’t drunk them since.

———-

Note: I posted Mike’s article on Writer River, as well as a ton of other excellent articles. Have you discovered Writer River yet? You can subscribe to the feed or to a daily email update. Then each morning, when you open your feedreader or email, you can start the day off with information that will help you do your job better.

But really when it comes down to it, there are only so many options — printed manuals, short guides, interactive flash guides, videos, online help, live training, reference cards, context-sensitive help, workbooks and exercises, or, usually the favorite, someone to stand by their computer and answer questions whenever they need help.

(I’m surprised how many people actually tell me that last option, as if in any kind of world that would be feasible.)

The most common responses go somewhat like this:

• I like to jump into the application and then turn to the help material when I get stuck.
• I want to quickly search the help to find an answer to my question.
• I would like the videos sent to me on a DVD please.
• I like to mark up the printed manuals with notes and tabs.
• Videos appeal to people who are visual learners. I prefer to have both video and print.

While it seems like such a simple task — ask the users what they want, and then deliver it — in reality it’s a difficult call. Imagine that you’re planning to feed a large hall of people. In deciding what to feed them, you ask them. But the responses are all over the place: some are vegetarians, some love steak, some prefer barbeque, others want salad, others want pork, others don’t eat pork, others like pizza, others want crab, others are allergic to seafood, and so on. Same goes with help.

However, despite the variety of learning preferences, I think there are several key principles that hold true for almost all of us:

• Long manuals intimidate us and bring out a sense of disgust and depression.
• Short quick reference guides, cards, or other quick material give the impression that the application is easy to learn — therefore we welcome short guides with open arms.
• When we have questions, we prefer to search for the specific answer rather than reading a manual from the beginning.
• When we don’t find the answer within 2 minutes, we give up and ask our neighbor or call someone.
• Seeing a process is often much more useful than reading about it.
• Visual images with callouts and other annotations make instructions easier to absorb while scanning, and our primary reading mode for help materials is to scan.
• If undergoing training, hands-on tasks at a computer lab are infinitely more valuable than a long demonstration at the front of the room.
• Videos are helpful, but if they’re long, or if the user has no control to skip around, fast forward, or go directly to bookmarks, a long video tutorial (more than 5 minutes) is unbearable.

Given this variety of ups and downs, usability principles and learning preferences, what set of help deliverables will most likely appeal to the widest audience? In most situations, one can’t create them all and do a good job. Maybe you’re magically able to single source everything into 7 different deliverables at once and satisfy everyone, but in my experience, that doesn’t really work.

A Telling Moment

My favorite response to the question — “How do you prefer to learn new software applications?” — was when a user pointed me to the Interactive Microsoft Office Guides. These guides were created my Microsoft to help people figure out where all the supposedly intuitive stuff is on the ribbon (I can just see the Microsoft ribbon developers saying, 3 years ago, “Oh users will get it, totally ….”

You might want to take a look at these guides. They’re Flash-based, interactive, and really engaging, not to mention helpful. They show a mock interface of the application. When you make a selection, it gives instruction on how to do the exact same task in Word 2007.

My Analysis

When it comes down to it, here’s what I think most users truly want:

• A comprehensive online source they can search and quickly find answers.
• Short quick reference guides (about 3-5 pages) in an attractive format.
• Short 2-minute video tutorials for the most confusing tasks.
• An ability to interact or contact a real person either virtually or physically.

Notice that I omitted the M word. There isn’t a 200 page print manual in the list. I have mixed feelings about this omission. At the last STC Summit, I attended a panel that discussed whether the printed manual was dead.

Unfortunately there wasn’t a definitive answer. When you omit the printed manual, 67% of the people complain, according to the panel. But apparently if you put the manual in PDF format, in place of a printed manual, the percentage of people who use it is exactly the same. So people don’t use the printed manual, but they complain if you don’t include it.

Creating a long manual is no easy task. To be usable, it needs a meaty index at the back that is thorough, full of synonym references and other user-intuitive phrasings. Additionally, you need cross references throughout. And then there’s a lot of layout and formatting. If you have images that you’re including, the resolutions differ from online and print, so often you need two sets. In many cases (if you’re using a good help authoring tool) you can mostly single source your online help to printed material in one go, but setting up the conditional tags, print styles, variables, cross references, and other considerations in your tool, as well as fixing the inevitable formatting errors, takes a long time.

Rather than labor away at this printed beast, I think I will, for once, skip it and focus on improving other deliverables my users more frequently request.

What help deliverables are you creating for your users and why?

Drop-down hotspots seem like they’d be all the rage — the ability to compress massive amounts of information into little spaces that are easy to scan. You can get around the bloated TOC that intimidates readers with its endless books that expand and expand. Instead you make your help file look thin and sexy.

Here’s an example of drop-down hotspots from Flare’s help (see image).

There’s a lot of text compressed into a little space. Cool — with one glance, you go immediately to the info you need.

Falling in love with this idea, I started putting hotspots all over my help file. This shrank the TOC considerably, making the help look more approachable, not so gargantuan. And then I realized something that stopped me cold … hotspots don’t chunk.

Sharon Burton has a nice post explaining topic-based authoring. The idea is that you write your tasks in separate little chunks, and then you pull those chunks into the outline/TOC that you want. So you can have an advanced TOC that has all the chunks, and then a quick start TOC that has just a few select chunks.

The problem with the hotspots is that they don’t chunk. You can’t pull one hotspot into your Advanced TOC and another into the other Quick Start TOC. Once you start using hotspots, you commit yourself to that chunk size. In the Flare example I’m using (see image), if the author wanted to strip out only the “How to print and distribute a hard copy version,” perhaps for a quick guide on printed material, he or she couldn’t do it — the hotspots don’t lend themselves to chunking. You’d have to include the whole family of hotspots into your TOC. That sucks!

So although you gain strides in usability, you lose the ability to manipulate your content into manageable chunks. Without those little chunks, you’re force yourself into a larger software manual with less flexibility.

Chunking may make life easier for producing multiple outputs with varied TOCs, but the TOC structure becomes bloated. If each hotspot becomes its own topic, you suddenly have three or four times the number of topics in the TOC. So you group the topics into more folders, and put folders inside of folders. Pretty soon the TOC is no longer navigable except by search.

At this point, feeling that usability and efficiency are not both attainable, the only thing left is to watch this cool exploding skateboard video.

]]> http://idratherbewriting.com/2008/02/21/my-love-affair-with-drop-down-hotspots-ends/feed/ 13 http://idratherbewriting.com/2008/02/11/are-gerunds-in-topic-titles-problematic-in-search-results/ http://idratherbewriting.com/2008/02/11/are-gerunds-in-topic-titles-problematic-in-search-results/#comments Mon, 11 Feb 2008 20:46:18 +0000 Tom Johnson http://www.idratherbewriting.com/2008/02/11/are-gerunds-in-topic-titles-problematic-in-search-results/ more »]]> I’ve been accustomed to writing topic titles as gerunds (for example, “Configuring the Monitor Display” or “Reformatting Your Hard Drive”), followed by specific steps that would begin, “To configure the monitor display…,” or “To reformat your hard drive….”

However, when I watched how an actual person used my online help file, I noticed he didn’t use gerunds in his searches. He typed his search like this: configure monitor display, or reformat hard drive.

When I search on Google, I also do the same: I use the form of the verb that expresses the action I want to do. I’m not looking to “reformatting my hard drive.” I want to “reformat hard drive.” I want to “configure monitor display.” I want to do something, to perform an action.

Grammatically, I think the gerund is more common. But given that the topic title plays a huge role in the search results, I’m thinking of saying goodbye to gerunds in topic titles. When the user searches for “reformat hard drive” the answer will more readily surface if that’s how I’ve named the topic.