I'd Rather Be Writing » help

Leveraging the wisdom of the 80/20 rule: Focusing on content that matters

Tom Johnson — Tue, 17 Apr 2012 19:46:19 +0000

The 80/20 rule, or Pareto’s Principle, states that 80 percent of the effects come from 20 percent of the causes. Applied to help authoring, this could mean that from 100 help topics you write, about 20 of the topics will be viewed 80 percent of the time.

Designers recognize the applicability of the 80/20 rule on design. Heat maps show that people only focus on about 20 percent of the page. This is where good designers will focus their energy.

: Focus your effort on the words that truly matter

Webdesign Depot explains:

Assuming this is a good indicator of where a user’s eye is focused, this supports the concept of the 80/20 rule. The most intense areas on the map could represent the 20% of the page that the user’s eyes interact with 80% of the time.

From that knowledge, as designers, we can make decisions that will help enhance and optimize the areas that the user is going to be habitually drawn to. (The 80/20 Rule Applied to Web Design)

How it affects help content

If this rule indeed holds true, how should the 80/20 rule affect the help content we create?

All too often we treat software documentation on a topic equality basis. Every topic usually gets our full attention and care. We slog through one topic after another, moving slowly but surely as we prepare our help system.

Instead, why not figure out the 20 percent of topics that most users will be interested in, and then pour the majority of our time into developing content for those topics?

For these high-use topics, we could add screenshots, videos, quick reference guides, FAQs, and more. Figuring out these topics is to identify the core — the beating heart — of the help content.

To increase the visibility of these high-use topics, we might also put links to these top 20 percent topics on the homepage of the help, or in special portals. This way if we don’t have context sensitive help, users will get to the information they need.

If only we knew …

But you may object that it’s only in hindsight that we can identify of our most influential topics.

This is true, but perhaps this is where the real change comes. I noted a few months back that we approach help authoring backwards. In a phased approach, the first release of help might contain a text-only skeleton of help content. The second phase, after you identify the frequently accessed topics and questions, could contain more multimedia and visuals.

Regardless of the approach, my point is this: I spend far too much time creating content no one is asking about. I should instead focus our time and energy on the content that matters.

A few more 80/20 applications

The 80/20 rule is such a fun rule, though. Why stop here when there’s so much more territory to cover? Here are a few more possible applications of the rule.

During your 8 hour day at work, you accomplish your most influential tasks in about 1.6 hours. (This is probably the time you actually spend writing, while the rest is taken up by meetings and other distractions.)

Although you put in hard work throughout the year, only about 20 percent of your effort makes a difference, while the rest goes unnoticed.

80 percent of the effect comes from just 20 percent of what you say. A full five minutes of praise followed by a brief but bitter and cutting negative remark sours all the positive.

A page with impressively written instructions but which is missing a critical step makes the entire procedure baffling and the experience negative for users.

In a blog post of 1,000 words, only 200 will be memorable.

80 percent of the funding in your department probably goes toward 20 percent of the products.

20 percent of your products probably make 80 percent of your company’s profit.

80 percent of the book you’re reading will be a waste of time.

80 percent of your time spent on the project will be in useless meetings. Except that a few key meetings, maybe 20 percent of them, will make meetings worthwhile enough that you can’t miss skip out on them entirely.

Of the 10 tweets you post, 2 of them get retweeted a ton of times while the rest fall into thin air.

Twenty percent of the blog posts you write will garner 80 percent of the traffic, while the rest languish unread.

80 percent of your team’s output comes from just 20 percent of your employees (don’t fire those ones).

A novelist who writes 8 novels really only gets notoriety for 2 of them.

A musician who becomes famous is recognized for her 2 songs, while 8 of the others are easily forgettable.

20 percent of your child’s activity will lead to 80 percent of your headache (e.g, screaming. jumping).

Your users will probably only use 20 percent of the features in your application.

80 percent of the calls to the support desk will be about 20 percent of the features of the application.

Those short few words of praise when you’re critiquing someone’s writing mean more than 80 percent of anything else you say.

I probably only use 20 percent of my English vocabulary, but I use these words 80 percent of the time.

My wife is right about 20 percent of the time, but her aggressiveness and memory helps her seem like she’s right 80 percent of the time.

At conferences, 80 percent of the sessions you attend will be mediocre; the 20 percent that you do attend will be memorable and worthwhile.

As a breadwinner, you’re gone from your family most of the time, but that 20 percent of the time you’re at home counts for about 80 percent of your influence.

20 percent of the punctuation marks available to you are used 80 percent of the time. (Think about the comma and period, rather than the colon, semicolon, dash, and ellipses.)

20 percent of your users give feedback, but their feedback influences 80 percent of the product decisions with the team because these users are so vocal.

20 percent of the tech comm gurus are responsible for 80 percent of the influence in the industry.

20 percent of what you eat contributes to 80 percent of your weight.

20 percent of your brain contributes to 80 percent of your thought.

20 percent of your dates contribute to 80 percent of your children.

Okay, I’ll stop.

Blog Sponsors

A Reverse Approach to Help Authoring: Writing Documentation Post-Release

Tom Johnson — Thu, 02 Feb 2012 06:33:20 +0000

When I first started as a technical writer, a senior writer taught me how to write documentation. Her approach, which aligns with the traditional way of doing technical writing, generally followed these steps:

Get involved as early as you can in the software development process. As soon as prototypes are available, or a functioning development environment, start the documentation process.
Think of all the main tasks users will do with the application. Make a list of the tasks and begin documenting them in careful detail.
As the application nears release, finalize your help material so that it’s ready when the application launches.
Once the application launches, move on to another project.

This traditional method of writing documentation places all the work before release. Sometimes I think the bulk of documentation should be written after release. This “reverse method” aligns more with support center philosophy. Some support centers believe you shouldn’t write anything until a user asks a question. Only then do you begin to document answers.

With a reverse approach to documentation, you place more emphasis on the help material after the release rather than before.

But you might object and say that our job is to anticipate the user’s questions and pain points so that when they do search the help file, the answers are there waiting. This in fact is Ginny Reddish’s premise in Letting Go of the Words. She encourages us to imagine a conversation with the user, anticipating their questions and responding as if in conversation.

I think imagination, even user interviews, are good techniques. However, too often I skip over this. I end up giving nearly every topic equal attention, documenting with careful detail both the obvious tasks and the difficult tasks. My imagination is usually an extension of the product manager’s vision and understanding, which I inherit from dozens of project meetings. The closer and more involved I get into a project, the less clearly do I see all the assumptions I’m making, the workflows I’m immune to, how blind I’ve become. No one can predict the future. How often have our anticipations and imaginations perfectly matched user reality? Do we even know the user’s reality?

With the traditional method of documentation, after the application is released, I’m not as closely involved with the project anymore. I don’t have my nose in JIRA; I’m not carefully monitoring all the incoming feedback. In my mind, I’m done. User pain points and frustrations often go unnoticed, while my attention shifts to new projects. I may add a topic here and there, or add some more detail, but by and large, documentation is mostly done when the application is released. I think that’s a harmful mentality that might be cured by a more reverse approach.

Let’s rethink the model. With a post-release documentation emphasis, the technical writer pays careful attention to every incoming question, comment, and feedback item from users. Whether through support center calls, forum questions, feedback emails, webinars, or other channels, the technical writer carefully monitors each question and begins building the help material from these questions. User feedback drives and shapes and structures the help material. It determines what we write, how much emphasis topics receive, and how visible we make those topics.

Now I’m not an extremist. I know that some help material is necessary when an application is launched. Quick reference guides and some basic help material would probably suffice. It would give something to the user to get started and not feel alone or abandoned. In some cases, a short series of video tutorials might also be helpful. After all, users need the most help when the application is newest to them, that is, when it’s first released. Abandoning the user in their time of greatest need may seem somewhat cruel and unproductive. I’m not saying no documentation should be written prior to release.

And yet, the long help file can wait. Wouldn’t we be much better to start writing help in an intensive, 100% heads-down manner during alpha and beta testing periods, and then during the first month of release? After all, how much time do we waste trying to figure out how a partially-built, bug-ridden application works in an unstable development environment? Wouldn’t our time be better spent waiting for the application to reach a near-production level, and then once that level is reached, focus all our energy on creating help material for it, based on questions and issues and frustrations users are experiencing?

Without a launch date for an application, there’s no clear date when documentation is done. In this post-release, reverse model, documentation can keep growing as long as users continue to ask questions and experience frustrations. Documentation is probably finished when the incoming feedback dies down, when most of the incoming questions can be answered with simple links to answers in the help.

Feb 3 update:

Check out this video from Greg DeVore that expands on some of the points I make in this post:

For a contrasting perspective on the idea of reverse documentation, see this post by Kristi Leach, When is it time to hire the technical writer?

Blog Sponsors

The “Home Depot Model” of Findability, or, Social Search

Tom Johnson — Tue, 10 Jan 2012 15:12:37 +0000

I walked into Home Depot the other day and, seeing a clerk near the entry way, asked where the storage boxes were. Immediately the clerk told me. After I found my boxes, I asked another clerk where the gloves and Sharpee markers were. Again, she gave the answer immediately. In my experience, apart from wandering aimlessly around the store for extended periods of time, this is about the only way to find things in Home Depot.

In the goal to find something, I relied on the social assets around me. In Greg Nudelman’s Designing Search, he talks about how people are increasingly turning to their social networks for information. Not only do social networks provide quick answers, but finding through social means allows you to draw upon people with similar interests.

For example, I have a large network of technical communicators that I follow on Twitter. If I have a question related to tech comm, it makes sense to ask my tech comm network. Most likely they could give better advice then simply searching the general web or turning to a friend on the basketball court.

Anne Gentle has written about social search on her blog Just Write Click. She notes that there’s an increasing trend to turn to your social network for answers rather than the help documentation. She explains,

Lastly, counts on click-throughs on Google searches may soon be surpassed by counts on click-throughs on social sites. Think about this for a moment. … you are more likely to get useful links by asking your friends and colleagues about certain topics than you are going to get them by searching on Google. This finding is a serious disruption for the web, if it turns out to be true. I haven’t seen studies yet that have numbers to support this claim, but I’ve seen it in slide decks about social support communities, community management, and the like. (See The Big Shift From Search to Social)

In other words, people may be searching on social sites like Facebook more than they search on Google because they get more useful information from social sites. As for metrics to support this, I recently saw this 60 seconds graphic:

Infographic by- Shanghai Web Designers

Unfortunately the original post doesn’t cite references, but if it’s true, in one minute there are 694,445 search queries on Google, while there are 695,000 Facebook status updates and 510,000 Facebook comments, along with 98,000 tweets on Twitter. If even ten percent of these social posts and comments are questions and answers, that’s a huge number of people using social networks as a means of finding and sharing information. It’s not a source to be ignored in the effort to make your content findable.

One challenge with increasing your influence in social search, of course, is bandwidth. It’s not possible to connect with so many people, right? One has only so much time to respond to forum posts, comments, and other social threads. Maybe not.

In a recent internal conference, one presenter explained how to get customers to adopt new products you’re rolling out. The presenter encouraged development teams to connect with key influencers in the community. If you can get the key influencers on board, they can help others, the presenter explained. Every department has that one person whom everyone goes to for help. If you give these influencers access to beta test software, reach out to them personally, and reward them for their helpfulness, they can be a huge asset in social findability.

In The Tipping Point, Malcolm Gladwell calls attention to several key types of people that can cause products to tip. Mavens and connectors (the terms he uses) can be key touchpoints for increasing awareness. When I walked into Home Depot and found a clerk, she immediately routed me in the direction I wanted to go. Although there were probably 50 people in the store, and only about 5 clerks, if I wanted to share information with all the people in the store, I’d focus just on the clerks.

The following graphic shows this workflow. As a technical writer, you don’t need to interact with the social web in its entirety. You just need to interact with the influencers (the mavens and connectors). These influencers are the forum champions who regularly interact with scores of people and thrive on helping and guiding others. They may be the administrative assistant in a department of executives, or perhaps prolific bloggers. The influencers will then interact with the rest of the user base.

If you focus on mavens and connectors (the key influencers), the rest of your end-users will get the information as they reach out to them.

In contrast, if you interact with users on a one-to-one basis, you’ll be overwhelmed with individual support requests and time-draining questions. I know that in past experiences, I’ve reached out to some users to gather their feedback. Later, I became their personal support assistant at beck and call whenever they had a question or problem. That kind of relationship can be very time-consuming.

If you do have the bandwidth to embed yourself in social sites and interact on a one-to-one basis, at least transfer the information you provide into the help content (assuming it’s not already there). This way you’ll convert the one-to-one interaction into a one-to-many interaction and allow influencers to get the information they need to help others.

Blog Sponsors

What You Cannot Do Sitting Down

Tom Johnson — Thu, 24 Dec 2009 07:23:42 +0000

I have mixed feelings about Christmas. People in our neighborhood have been bringing over treats all week — a chocolate pie, a peanut butter pinecone bird feeder, sparkling apple cider, brownies, rice crispies, honey, marmelade jam, Stephen’s hot cocoa, sugar cookies, and other food. They bring them with such pace and vigor you would think we were either starving or desperately in need of fattening up.

Jane has been making a list of everyone who has dropped off food so that if we do decide to make little neighborhood treats, she knows exactly who to take them to.

I told her gift reciprocation is a bit ridiculous. Making sure you respond appropriately to everyone who gives you a gift misses the point (though I realize it is polite).

Sometimes during Christmas the Grinch in me comes out. The concept of Santa (initiated by Saint Nicholas?) seems a bit of a backfire, since it refocuses Christmas on commercialism. All the buying and buying, and singing the same old songs again and again, kind of wearies me.

We recently went to Temple Square, which has thousands of elaborately strung Christmas lights saturating every tree limb and branch, floating lights on fountain ponds, high school choirs singing every half hour in the Tabernacle and Assembly Hall, a full-size nativity scene with music and narration, and other eye candy.

I enjoy the spectacle now and then, despite the cold, but the choir puts me to sleep. As soon as they start singing, I’m yawning and slowly nodding my head to the side until I catch myself. In a half hour, I’m ready to go back home and watch a football game.

I have been trying to get into the Christmas mood. At work I switched to a Christmas station on Pandora and listened to it for almost two days. But after a while I changed it back to my Bob Marley (I don’t know why, but I love reggae).

Our team Christmas party has been scoped down to a brief treat-trade. I didn’t push for a special party at someone’s house, because I already have enough December socials. (Surprisingly, no one else pushed for it either.) There’s plenty to do during December — a Christmas breakfast at the Church, an Elders Quorum party, a family Christmas party, Christmas card deliveries, shopping, and on and on.

Today I was running on a treadmill in my company gym. (No, I don’t run regularly. I think the last time I’d run was about three weeks ago.) I have this little routine where I run for about 4 minutes, walk 1 minute, run for another 4, walk 1, and so on, but each time increasing the speed .1 mph.

While I was running (still on my first iteration), a guy in a wheelchair wheels into the room and starts dragging over one of the pieces of equipment. He started dragged what looked to be a sitting curling machine, but it was obviously some orthopedic device. He dragged it while sitting in his wheelchair, inch by inch, scooting it awkwardly toward the windows and door.

I couldn’t figure out exactly what he was doing with it. At first it seemed he was dragging his favorite machine over by the window so he could … work out in the light? It was a bit cold and dark in the gym (and the TV was broken). But then he started wedging it up against the door, moving it at several different angles. I watched him while running, wondering what he was up to. It was both entertaining and mysterious.

He dragged it in a jerky motion again. Because he was in a wheelchair, he couldn’t pick it up. It finally dawned on me that — yes, despite the impossibility of the task, he was actually trying to drag the machine out the narrow door onto the sidewalk outside.

I stepped off the treadmill and briskly walked over to him. Are you trying to get the machine out the door? I asked. Yes, he said. I started to help him with it. He opened the door, and I tilted the machine sideways, and then lifted it a bit and maneuvered it in a L direction to wrap it around the corner. I could barely get the machine out myself, and I’m a big guy. But since I often get conscripted into moving projects at my church, I know how to fit furniture around corners.

The machine, he explained, helps him help stand up and stretch his body. It’s the only way he can stand up. But he said he doesn’t have time to get the gym as much as he thought, so he’s taking it back home.

I wheeled the machine down the icy sidewalk and into the snow-banked parking lot over to his Jeep Cherokee, where he needed to move the machine into the back. It wouldn’t fit without some disassembly, so we ended up leaving it beside his Jeep while he went after a hex wrench in his office to take off a bar.

I told him to get me from the treadmill when he found a wrench and I would help him load it into the Jeep. But he never returned. I’m guessing someone else helped him. Or he managed to do it himself.

As I started running on the treadmill again, I thought about this man attempting to move a weight machine so difficult for him to do alone, sitting in a wheelchair. He had brought it in piece by piece and assembled it here, he explained. That’s how he’d gotten it through the door in the first place.

Last year we had a quadriplegic guy in a wheelchair, Chad Hymas, come talk to our department. Chad said he had to rely on the kindness of people every day to help him into his car and to do basic things. It’s humbling, he said, but it filled him with gratitude everyday for the generosity of people, he said. (Somehow he is able to drive — don’t ask how. He can move his arms and operate a brake a gas pedal with his palms.)

As I showered and returned back to my cube to work on some documentation, I periodically thought about the wheelchair guy, rewatching him drag the unwieldy machine by himself out the narrow door.

I’m not always as helpful as I should be. Several days ago, when I was shoveling snow from my driveway, my neighbor’s mother actually got stuck in her driveway. I offered to push, but she declined. Her daughter (a complete recluse) came out and added salt while the mother shoveled the rest of the snow. I watched passively, chipping away at some remaining ice in my driveway.

The experience in the gym made me rethink how to help others. I didn’t ask. I just did it.

That night I came home and decided to make some neighborhood treats — both for Jane’s reciprocation list and others. I took two of my children to the store in their pajamas and moon boots and scouted out dark and white chocolate for pretzel dipping.

With Sally’s help, we conceived a silly poem — We hope you enjoy these chocolate sticks / you can eat them lick by lick …. And then the next night we delivered the treats to a string of houses — both to people who had given us gifts, to some of our friends, and to a handful of others.

We drove in the minivan, stopping at each house. The kids would run up the snowy driveway to the doorstop, gently set the bag of chocolate pretzels down, and then knock and run. They ran as if door-ditching, and would say Go! Go! Go! when they got back in the car, urging me to drive off. The person whose house we dropped the treats off at would inevitably open the door and look out with a confused look, and then they would look down and notice the Christmas bag on their porch. Sometimes they waved as we drove off. Other times they just picked it up and brought it in.

I’m starting to like Christmas, I guess.

Blog Sponsors

How Google Does Help

Tom Johnson — Sun, 28 Jun 2009 04:22:13 +0000

With all the talk about latest trends and avoiding extinction as communicators, and integrating web 2.0 and wikis, blogs, podcasts, and other interactive social media into help, it’s a good time to look at how Google — practically the leader of the web — does help.

Last week Google released Google Voice, a service that allows you to integrate all your phones into one number and includes a host of features, including voice mail, recording, conference calling, and other services.

To help users get started, Google Voice has a list of 20 short videos. Only the overview video contains animation. It’s certainly the video they’ve put the most work into, and it also functions as marketing collateral.

The other videos are fairly simple, with short looping background music, professional voice talent, and a read script. The defining quality is that each video is short, some as short as 25 seconds.

The videos aren’t integrated with the text help. So if you don’t feel like watching videos, you can’t easily read the same topic. Google Voice does have help text, but it’s on another page, only linked to from the videos with a tiny, hardly noticeable help link in the footer. It’s almost like one group produced text, another produced help, and they published them independently.

The video windows are small, under 500×500 pixels. The small video window allow you to easily move from one video to the next without losing your place in the site. If you click outside of the window, the window doesn’t automatically minimize, which is nice. You have to close the pop-up window to go back to the list of videos.

All the videos are pulled in from Youtube, so they’re shareable. After one video ends, you see a list of related videos, but the related videos aren’t other Google Voice videos. Instead they are other Google services. So the related videos somewhat fail if you’re trying to learn more about Google Voice.

You can’t comment on the videos, or upload your own, or do anything other than watch them. Unlike the Michael Pick videos on WordPress.tv, Google’s videos are somewhat boring. Except for the overview video, which contains an animated stick figure, they lack a sense of being cool. They feel a bit corporate.

Similar to the length of the videos, the help content is also short and to the point, but the help topics are too text-heavy, with almost no illustrations, diagrams, or screenshots. The pages are embedded on the web, and navigating the topics is somewhat tedious. A search field appears at the top of the help, but if you search for the word “videos,” nothing appears.

Glaringly absent is any printable manual. You can print a single page, but not a group of pages in a PDF manual format. Additionally, Google does not provide any kind of quick reference guide to get started.

You can’t comment below the help topics, but there is a forum. The forum allows you to be notified by email and see the most popular discussions. You can also read a Google Voice blog, but the blog, like the help and the videos, isn’t well integrated with the rest of the help materials. It somewhat lives on its own. Google’s blog also takes the backward position of disallowing comments and only allows linkbacks to the posts.

One interesting characteristic of Google Voice help is a lack of parallelism in the topics. Here’s a list of video topics:

Call screening – Announce and screen callers
Listen in – Listen before taking a call
Block calls – Keep unwanted callers at bay
SMS – Send, receive, and store SMS
Place calls – Call US numbers for free
Taking calls – Answer on any of your phones
Phone routing – Phones ring based on who calls
Forwarding phones – Add phones and decide which ring

The help topic titles are similarly unparallel. Usually help contains all verbs or nouns in a more parallel list.

My Analysis

Google puts a lot of effort in the overview video. That’s a smart move. When people want to learn about Google Voice, the overview video communicates the service in a catchy way, with more of Google’s branding. This video is probably watched thousands of times (a lot more than any other video), so it makes sense to go to the effort of including animation.

What I don’t like about Google’s help is the lack of integration between the video and help content. Not every topic deserves a video. Many times I’d rather read the help. And sometimes I’d rather watch a video. Separating the two formats so strongly is a poor usability move. The forum and blog also need to be more closely integrated with the other help materials.

Additionally, the lack of any printed manual makes me think Google has no single sourcing strategy. The help content is probably just written as regular text on each page. I would have appreciated the opportunity to print a quick reference guide or short manual, only because reading on the web is a nonlinear experience, and moving from one topic to another without any logical sequence can be tiring.

I also think Google chose the wrong voice for its videos. Google is playful, young, and irreverent. But the voice they chose is professional, corporate, scripted, and somewhat ordinary.

I’ve been thinking a lot about voice in videos. Professional voice talent is not necessarily engaging. It sounds professional, but a professional voice isn’t always what users want, even if it’s what they expect. Users want a voice that is friendly, engaging, conversational, and real. I wouldn’t even mind it to be a bit spontaneous.

Blog Sponsors

Write Answers, Not Documentation

Tom Johnson — Fri, 22 May 2009 12:36:54 +0000

Write Answers, Not Documentation

Blog Sponsors

Help on Movable Type Blog Format — Jing Help Center

Tom Johnson — Tue, 06 Jan 2009 14:34:20 +0000

Help in a Movable Type Blog Format — Jing Help Center