I'd Rather Be Writing » users

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

Looking at Breadcrumbs in a New Way

Tom Johnson — Fri, 06 Jan 2012 04:09:04 +0000

One of the findability features in our help systems that we often overlook is the breadcrumb. Breadcrumbs typically sit above the page title and highlight the hierarchical path that leads to where you are. Here’s a screenshot of a typical breadcrumb, taken from Adobe Illustrator’s help:

Greg Nudelman discusses breadcrumbs in one of his chapters in Designing Search: UX Strategies for eCommerce Success. This post mainly details notes from Nudelman’s book.

One problem with breadcrumbs, Nudelman notes, is that “breadcrumbs cannot show customers where to could go next. They show only where they’ve already been” (p. 199).

Nevertheless, Nudelman says the breadcrumb aligns with a search/browse pattern that supports common finding practices. Nudelman cites a presentation by Peter Morville called “Search & Discovery Patterns,” where Morville explains that “browse and search work best in tandem… The best finding interfaces achieve a balance, letting users move fluidly between browsing and searching.” (p. 203-4)

In other words, when looking for content, users prefer to search and browse, browse and search. Users perform a combination of the two as they try to find what they’re looking for. This is because, Morville explains, “what we find changes what we seek.” For example, search results for your initial query might show you the correct terms, which then informs your next search.

Breadcrumbs are powerful tools because users can easily modify the breadcrumb path to browse the information they want to see. Nudelman explains,

Providing the ability to change attributes while automatically retaining all relevant query information turns the breadcrumbs into a powerful and flexible finding mechanism, without making the resulting interface overly complicated or difficult to use. (p. 210)

For example, in the above screenshot, I may not want instructions for creating a drop-shadow effect. But rather than returning to the raw search and formulating a new query, I can click the Special Effects breadcrumb and browse the other special effects available. The breadcrumb allows me to modify part of my search without starting over from scratch. Nudelman says users would rather salvage part of their search and refine it rather than starting over:

In my research, people seldom want to start the query over completely from scratch, unless they specifically indicated this action. Instead, a vast majority of the people interviewed wanted to retain as much of the query as possible with every change of the facet values and desired the system to help them construct a query that “makes sense,” gracefully dropping facet selections that no longer applied to their modified query. (p. 208)

One problem with breadcrumbs in most webhelp system is that they perpetuate the myth that content lives in just one place, which is not necessarily true. Content in the digital space can appear in many different arrangements and paths.

Nudelman notes that Edmunds.com’s search results show tag selections as breadcrumbs.

I would like to see webhelp move away from a single hierarchical organization of content to one that simply shows tags that are stacked together in the query. This shift would be a new paradigm for the way help is organized. In Edmunds.com, each of these keywords is metadata for the content. There may not be an official hierarchical order to the content, like there is most webhelp systems. The order is dynamically generated based on the metadata you select.

I recently wrote about tags as being more of a web-based method for classifying information. See Using Tags to Increase Findability.

For more information about Greg Nudelman, see his site, Design Caffeine.

Blog Sponsors

You learn more from users in 5 minutes than you do from 2 weeks of project meetings

Tom Johnson — Tue, 14 Sep 2010 14:20:32 +0000

I recently had a project with a small group of users, maybe 35. I joined the project about a month before the scheduled release. I wasn’t sure what kind of help the app needed, or what format. A wiki? Screencasts? Online help? A short PDF?

I talked with the lead customer, and he hadn’t given much thought about help. I talked with the project manager, a quality assurance engineer, and a developer. The PM didn’t know what kind of help the app needed either. The QA engineer thought it needed a few pages of help; a developer said it needed maybe 150 pages. After floundering around for about a week, I realized I was shooting in the dark.

I asked the interaction designer for some names of users I could contact, and he supplied me a name. After talking on the phone with the user for 5 minutes, I knew that my entire previous direction was wrong. They didn’t need a robust wiki. “If you created a help system,” the user said, “I’m really not sure anyone would use it. We all know the process so well here. The only thing we may need help with is to find where something is in the interface.”

This lightened my load incredibly. The way our department often works, we create applications so customized to a specific business process that only users within that business department understand how the application will actually be used. Trying to penetrate this business process requires learning an entirely new culture and knowledge base. But often it isn’t necessary to document this business knowledge — it all depends.

When I started the project, I was fixed on creating documentation that explained not only the how, but the why and who and where and other context. Now I’m basically creating a slideshow of screenshots with some callouts indicating where things are in the interface. I figure it will save me about 2 months of work and will actually be looked at by the users — all because of a brief phone call with users. I realized that I can learn more from talking with users for 5 minutes than I can from 2 weeks of project meetings. Why is it that I don’t talk to users more frequently?

photo from Flickr

Blog Sponsors

If No One Reads the Manual, That’s Okay

Tom Johnson — Mon, 28 Dec 2009 00:58:56 +0000

Most people take time off during the holidays, so if you don’t, you end up mostly sitting alone at work, wondering why you’re not taking time off too. I wanted to follow Penelope Trunk’s advice about pursuing your pet projects while working during the holidays, but instead I was trying to finish a project with an end-of-year deadline.

The project I’m working on is critical, but it has only about 3 to 4 users, most of whom are already familiar the application. One of the users even drives the design. The manual I’m writing, which is nearly 200 pages, is mostly a safety measure for business continuity planning. I don’t expect anyone will ever read it.

It’s a project I managed to procrastinate for months, working on other projects, even outside the scope of my regular assignments. The main deterrent, I believe, was my perception that no one needed the manual. The users seemed to be getting along fine without it.

And so as the year ticked to a close, instead of learning more about Mediawiki and screencasting and After Effects, I spent my time updating a 200-page manual that I don’t think anyone will ever read. It will be printed out, three-hole punched, and placed in a binder to collect dust on a shelf.

The idea that “no one reads the manual” is certainly not new. But despite this accepted truism, most of us don’t entirely believe it. I think we always have an imagined audience in mind when we write. I often imagine a confused user searching for questions in the help, or a new employee printing out the manual and reading it, making notes in the margins and going step by step through tasks a manager marked. I imagine a user familiar with an application suddenly dumbfounded on a specific screen, clicking help and scanning for answers.

I need this fantasy about the way my manuals are used because without it, there’s no motivation to write.

Charles Hurwitz, a technical writer in Israel, recently had an experience that confirmed the idea that no one reads the help. Charles writes,

Early on in my tech writer career I had the eye-opening experience of walking into an engineer’s office and seeing a multi-volume set documentation on his bookshelf still covered in shrink wrap. I thought to myself that after all the months work on the manuals he should at least have the common human decency to take off the shrink wrap. It’s like buy a painting and hanging it with the painted side facing the wall. Since then when people ask me what I do I tell them I write books that nobody reads. (It’s Official–Nobody Reads the Manual)

In his post, Charles also references a survey by Gadget Helpline that found 64% of men and 24% of women don’t read the manual before calling support (Gadget Problems Divide the Sexes).

It’s not just a matter of putting the manual gently aside. Users actually despise long manuals. Ron Jeffries writes, “Your customer hates big manuals. He has shelves and boxes full of them just like you do.” (Manuals in Extreme Programming).

I believe the discomfort of reading a 200-page manual compares with the pain a dentist administers when removing a tooth, or the frustration an IRS writer creates when he or she makes a long, complicated tax booklet users will have to figure out.

Joel Spolsky, a programmer and web entrepreneur, says,

Even if they have the manual, frankly, they are simply not going to read it unless they absolutely have no other choice. With very few exceptions, users will not cuddle up with your manual and read it through before they begin to use your software. In general, your users are trying to get something done, and they see reading the manual as a waste of time, or at the very least, as a distraction that keeps them from getting their task done. (Designing for People Who Have Better Things To Do With Their Lives)

When I interviewed Mike Hughes several months ago for a podcast, he said the conclusion of most studies about how people use help is that they don’t actually use help.

Some writers still find hope in the rare instances when users will consult the help. Sheila Fahey of Cherryleaf explains: “When things go wrong and it matters to the user, they will seek assistance. They will look for the easiest way to get to the information they need to do the task. If this is the manual, then they will use it.” (If no-one reads the manual, then why bother?)

Looking at help this way is seeing the help as an emergency kit in a car. People won’t normally need the emergency kit, but when you’re stranded on the side of the road in the middle of nowhere and hungry and cold, you will use it. You will break it out of the plastic wrap and actually use it.

Flipping Sides

Not many writers consider the positive aspects of users not reading the manual. If you do a lousy job on the manual, or if some SME discovers typos and inaccuracies, you can just laugh it off by saying no one really reads the manual anyway.

But consider the opposite scenario where everyone reads the manual. Is this a scenario you want? No. Because if everyone has to read the manual to figure out the product, it means the product is so unintuitive and user hostile it’s probably going to tank on the market and you’ll soon be out of a job anyway.

Also, if so many people are consulting the help, you probably aren’t contributing enough on the design/usability side of your technical writing role. Remember that you’re part of a team building a solution to a problem. You want the user interface to be simple and intuitive enough to not require a manual. So if only 10 percent have to consult the manual to figure out the product, that’s a good thing.

No One Knows

Knowing exactly how often help is used and by whom is hard to measure. If your help is entirely online, you can measure basic hits easily enough. But if it’s distributed in print, you can’t really know.

For example, on Christmas day, my sister-in-law was putting together a fish tank and filter for her boyfriend. (By the way, a Betta fish is a cool present to give someone.) Installing the pump and filter was confusing. Was the pump supposed to be above or below the waterline? Was it supposed to be making that humming noise?

At one point, just as she and other family members were getting frustrated, one person jeered, I can’t figure it out, and there’s no manual at all!

More people get frustrated assembling things on Christmas than on any other day of the entire year. It’s a day manuals are both cursed and blessed. But in this scenario, no doubt the company that created the filter was unaware of the frustrated user stuck without a manual. We’re often in the same position of ignorance about our users.

If you think about it, the technical writer is in an unusual role. Users hate the presence of manuals as much as they hate missing manuals. They despise lack of detail yet curse length. If no one reads the help, your position lacks value. If everyone reads the help, you’re on a sinking ship. Ideally, you want the user interface to be simple enough not to need help. But the more you contribute to this user interface simplicity, the less you’re needed.

Conclusion

As the year closes and the project manager is off skiing and the developers are playing video games and the quality assurance engineer is organizing his closet, I’m pounding out the last topics of a 200-page manual that I will soon deliver to a group of users who will smile and thank me for the manual, knowing they don’t have to read it or critique it anymore, but can just put it proudly on their shelf, or maybe even in a storage box.

If I find out, through feedback or on-site visits or other means, that they don’t ever read the manual, that they have never actually opened the manual beyond the table of contents, that’s okay. I hope they never have to.

Blog Sponsors

What Users Don’t Care About

Tom Johnson — Sun, 12 Jul 2009 03:45:45 +0000

It seems most of the conversations in our industry today revolve around value. If you go to stc.org, the large graphic at the center of the site says “The Value of Technical Communication.” (Given the recent events in the STC, to me the graphic really reads, “The value of the STC organization.”) At any rate, technical writers have been talking about demonstrating value to employers in quantifiable ways for years.

Technical writers frequently talk about value, but much of the value is invisible to users

Part of the problem in our attempt to demonstrate value is that our help deliverables look the same as they did 15 years ago, more or less. Online help and a PDF manual. It’s not a format that engages users. The web marches forward with innovation after innovation, while the technical communicators are figuratively hunched over keyboards, staring at CRT monitors, wearing 1950s horn-rimmed glasses, typing away. At times it seems the technical writer is a relic of a past tradition, a figure barely hanging on to the rapid pace of technology in the 21^st century. Or so it would seem.

Although that’s the general impression, actually technical communication has had considerable innovation lately. DITA has provided an advanced XML architectural standard for single sourcing that all technical communicators can implement. Even putting aside DITA, single sourcing technologies with help authoring tools have become more common. The old method of copying and pasting to produce multiple deliverables is a primitive practice no longer typical. We’ve moved into an age of efficient authoring. We can now generate seventeen deliverables from just one, original source. Brilliant!

But whatever methodology has changed in our creation process, the value of our industry’s innovation only trickles down to the user, and in an almost unnoticeable way. You may have single sourced your documentation from a large snippet library, breaking up your topics into granular chunks that you’re cleverly reusing through your topics, and pulling it all together with conditional builds. But to the user, it’s the same old online help and PDF manual.

The user could care less whether the PDF manual is single sourced. Keith Anderson (on Twitter, @suredoc) writes,

I personally believe you can argue the merits of DITA or single sourcing all day long, but the dirty little secret of our industry is simply that users don’t care. They just don’t care. They do know how they want information and will consume the information in ways that are comfortable or familiar to them (“Sheep, Chaos, and User Experience”).

In other words, it doesn’t matter to users how you created the documentation. What matters to them is what you create. We have a somewhat similar policy at my work. It doesn’t matter whether you work 20 hours or 80. You just have to get the job done. Our CIO even says we can leave to go watch our kids’ soccer games at 2 p.m. if we want, as long as we get the job done. (He doesn’t mention that it’s nearly impossible to finish all your work.) But the focus is on the output, the deliverables, not the clever or cruel process we endure to create them.

Here’s another example. Did you happen to read Richard Hamilton‘s Managing Writers? It’s formatted in Doc Book, did you know? Doc Book streamlined Richard’s printing process, enabling him to stylize the format in different ways without altering the source. He can print a news article format, a booklet format, and a book format from the same source by just altering a stylesheet. He can also generate the content as HTML, ePub, CHM, or PDF without any additional work.

Despite the innovative format, to most of us who read it, it’s still just a book. It looks like all the other books on our shelves. I think most of us, in reading the book, might admit that we don’t really care how he created the product (except from a professional curiosity perhaps). Our primary purpose is in the product itself, the content, not with the way it was made. I don’t really care if Richard stayed up past midnight every night for two years writing the book, or if he wrote it on the bus, or whether he piecemealed from a private wiki, or published by typing with two fingers on a netbook sitting in a café in Italy while eating plum pastries. What I care about is the end product.

Because users value the product rather than the process, and tech comm’s innovation has been in the process, technical communication comes across as stagnant, without innovation, and stuck in the past, while web technologies march forward. The evolution of the web, from static pages in primitive HTML to rich, audiovisual, dynamic content you can interact with by commenting on, subscribing to, trackbacking, aggregating, and mashing up demonstrates tangible progress. It’s an advancement in value that you can see and feel in every way, unlike the invisible advances in tech comm.

The frustrating part is that innovation in technical communication—however invisible—does actually benefit the user in a number of ways. According to my colleague Paul Pehrson (@docguy on Twitter), because of DITA and single sourcing, users now have more consistent documentation. Previously, with the copy and paste method, multiple deliverables would invariably be out of sync—updates would be made to one but not the other. Copying and pasting would also exhaust technical writers, and last minute changes were a nightmare.

Now with single sourcing, synchronization issues are no longer a problem. Last minute changes can easily be accommodated. Topics in multiple sources are the same because they’re generated from the same source. Translation costs are also reduced.

Because of single sourcing, we can also provide more custom, role-based guides. Rather than delivering one enormous reference manual, we can deliver smaller guides for each role. And we can provide all of this information more quickly, with fewer resources producing it. One person can really generate 17 guides, and even update them nightly through an automated build process each time he or she makes a small change to the content during the day. The reduced time decreases the cost of the product overall, making documentation both cheaper and more accurate.

Still, despite these advancements, the user still holds a manual in hand and thinks nothing has changed in decades. This is perhaps the flaw of DITA: no noticeable increase in value in the deliverable. In fact, the plain formatting and generic style may even appear to be a decrease in value. Without any tangible, immediately felt benefits to the user, the deliverables seems stagnant and lacking innovation. It’s a misunderstanding, though—somewhat like the poor, overworked employee who puts in 80 hour work weeks but has nothing extra to show for it.

Blog Sponsors

Podcast: Make Your Help Indispensable, Safeguard Your Job

Tom Johnson — Sun, 01 Feb 2009 04:58:36 +0000

Download MP3 (to download, right-click and select Save Target As)
Length: 30 min.

In this podcast, I talk with Mike Hughes, second vice president of the STC, about his latest UXMatters article, “Straight Talk: Surviving Tough Times as a User Assistance Writer.” We talk about how to make help more valuable, more worthwhile and user-focused, so you don’t lose your job when companies begin laying off employees based on lack of value.

Here are a few other topics we cover in this podcast:

Where help must appear to be used, and how to pitch it to the user
Why documenting everything is sometimes the worst thing you can do
What it means to make your help “a mile wide and thirty seconds deep”
How identifying points of pain and information gaps can help you avoid writing obvious instructions
Why tools and technologies can distract you from the content

About Mike Hughes

Mike is a seasoned technical communicator with 20 plus years of experience. He currently works for IBM Internet Security Systems as a user assistance architect. He holds a PhD in Instructional Technology from the University of Georgia and a Masters in Technical and Professional Communication from Southern Polytechnic State University. Mike also contributes regular columns to UX Matters and writes a blog at http://user-assistance.blogspot.com.

Blog Sponsors

Funny video about knowing your users

Tom Johnson — Wed, 17 Dec 2008 13:53:52 +0000

A friend of mine sent me a video that provides instructions for converting your TV signal from analog to digital.

Blog Sponsors

10 Ways to Gather Feedback from Users

Tom Johnson — Sat, 18 Oct 2008 03:22:44 +0000

User Knowledge Empowers You to Drive the Team

Ever since I came back from Doc Train West and had my epiphany about the transformative, empowering nature of user knowledge with the tech writer role, I’ve wanted to build stronger connections with my users.

Having extensive knowledge of user behavior can make you a valuable asset on any project team, allowing you to deliver key advice on application design and development. Additionally, as in any writing situation, a detailed sense of audience helps you write content much more useful to the audience.

In short, the more user knowledge you have, the more powerful you are as a technical communicator. Here are 10 ways you can gather feedback from users.

1. Create a “Send Feedback” Link in Your Online Help

I add a Send Feedback link on every page of my online help. This allows users a point of connection when they can’t find what they’re looking for in the help. I add the Send Feedback link on the master page of my webhelp target, so one instance in the footer automatically propagates to every help topic.

The link contains a javascript that opens the user’s default email program and inserts the absolute URL of the help topic he or she was on at the time. This link is important in identifying the problem the user was trying to solve, because often the messages users send are cryptic and ungrammatical. It also lets you know they were actually in the help. Here’s the script:

I’ve heard some people say they have feedback links in their help and never receive any customer responses. For an application used by about 1,500 people, I receive about one feedback email every two weeks. The email is automatically distributed to a list that includes our core project team.

It’s cool to receive feedback from users, except when they point out an inaccurate step in the help or a broken link. At that point it’s a little embarrassing, but still preferable to blissful ignorance.

Other times they’re trying to do something that’s not possible in the application. For example, two nights ago I receive an email at 9 p.m. from a user asking how to perform a task. At first it wasn’t clear what he was asking, but by visiting the embedded URL, I could piece together his real intentions.

The program manager saw the email and immediately responded, and I chimed in to the conversation as well. The user who asked the question was stunned at the quick response, and I ended up fixing a step in my help.

2. Track Help Usage with Analytics Tools

Most companies have an analytics tool to track visitors to their corporate site. For example, we use Omniture at my work. Others may use Google Analytics or other site metric tools.

You can add a script to each of your pages that tracks the pages most commonly viewed. From these stats, you can see what problems users struggle with most. (If you don’t know where to get the script, ask your company’s web metrics guru.)

Unfortunately, looking at help site metrics can be a little depressing. I counted about 37 visitors in a month once. Whatever the numbers, viewing help metrics is a reality check.

You can also pull statistics from your application’s database or logs (assuming your application has them, and that you can convince a techie to get them for you). This can help you understand actual application usage and trends. Based on the most commonly used functions, you might strengthen those sections in your help. You could also make your help’s home page a list of the top 10 topics users search for.

3. Monitor Support Center Call Logs

If you have a support center, the service agents usually log calls in an incident management system, and then document solutions and workarounds in a knowledge base. It’s important to stay aware of support center trends. You can often generate reports from their support logs.

You can also view the hits on various topics in your support center’s knowledgebase. If possible, try to integrate your own help material with the support center’s knowledgebase.

At my organization, the service desk agents have an incident management system that ties in with their knowledgebase. Apparently the integration is so close that keywords from the incident log automatically show relevant search results from the knowledgebase.

The first report I analyzed from the support center showed me that a lot of users had trouble logging in to the application. They also needed help setting up their committees and designating the correct roles. Using this knowledge, in the next release of the application we added additional help links to the login page.

4. Observe Users in Their Environment

It’s helpful to observe users in their own environment. For example, the main users for one of our applications are secretaries. I happen to sit near a secretary, and from casual observations, I can tell she spends much of her day scheduling meetings in Outlook and handling other administrative tasks through email.

She’s not a break-it-to-understand-it techie by any means, but she’s hard working and organized. And she seems to prefer print material. Mostly she seems exasperated most of the day, constantly looking at full Outlook calendars.

Wear your help ethnographer hat and go visit your user’s environment. You can often learn a lot about your audience. At a previous company, we provided documentation for financial analysts, whom we never met. One day we went on a field trip to one of their offices. The financial analyst we intended to visit was gone (playing golf with clients, I think), but the secretaries were busy at their desks, buried in paperwork.

We finally did meet some financial analysts at a smaller office. It turns out they had never read the documentation we wrote, as far as they knew. It was somewhat of a shock to both of us. Previously I pictured an aggressive financial analyst skimming the help as he logged numbers in spreadsheets. In reality, we were mostly writing for their assistants.

5. Contact Your Users Periodically

You can contact your users periodically with a friendly email asking if they have any questions or feedback about the application. I don’t often do this, but I have been starting to do it more lately.

Try to think of the last time someone from a major product you use (Microsoft, Adobe, TechSmith, etc.) contacted you to see how the product was working for you. Imagine if a person from Adobe just called to see if you needed any help with Photoshop. My jaw would drop to the floor, and I would never forget this non-marketing-based outreach.

An email can provide an important piece of contact information when a user needs help. They may not respond at the time (in fact, they may probably ignore you entirely). But when they’re frustrated, they’ll remember your email and seek you out. And people who find answers from one source tend to return, like a stray cat to a plate of milk.

Of course, being sought for help may be the last request you want — another to-do item on your already overburdened plate of assignments. If that’s the case, then yeah, you may not want to be reaching out to customers. But if you’re trying to fill yourself with user knowledge, the email may pay off.

6. Build User Profiles/Personas

It’s becoming more and more common to create user personas as means to ground your understanding of your audience. Personas are composite sketches that describe a typical user and his or her behavior. More specifically, a persona is a stereotypical description of an imagined user of your application, complete with a fake name and photo and all kinds of quirky details. Personally, I’ve never written a persona sketch, but I do have several in the back of my mind as I write.

You can pin these personas up around your computer or office wall (they might make great conversation starters) to help you remember who you’re writing for. Envisioning your audience as specific people (“Jim,” or “Susan”) can help you write with greater clarity and focus than writing with only a vague crowd of faceless people.

7. Establish Regular Communication Through Biweekly Tips

Almost no user ramps up to the power level on your application the first week he or she gets access. Instead, the user most likely learns just enough to get by; he or she figures out how to accomplish the needed basics. In this moment of initial learning, the user may read a dozen pages of your 200 page how-to guide. But once somewhat comfortable, he or she lays the manual in its coffin and continues on day after day with basic tasks.

A biweekly tips newsletter (housed on a blog, with posts sent in emails to users) can help spoonfeed that user little bits of knowledge in consumable fashion, helping ramp the user up to a power user in a period of time.

People can learn immense amounts of material if the learning is rationed out, chopped up into little segments and distributed every other week or so. Even the overworked secretary can watch a two-minute video tutorial and suddenly understand that cryptic feature that was really hard to explain in the documentation.

When you spoonfeed your readers with tips, you don’t only ramp your users up to a more advanced level, you also establish a line of communication between you and the users. You strengthen your role on the project team as the conduit and connection point for all those using the application.

8. Become a User of the Product Yourself

There’s no better way to understand your users than actually becoming a user of the same product. If you can start using the product you’re documenting, integrating it into your daily workflow, it can provide a tremendous perspective boost.

The main product I document right now is a meeting management and decision-making tool. When I started using it to record and track decisions for our own tech writing department, it opened my eyes about so many features.

For starters, I noticed that the authoring window was small. A button on the web editor toolbar, however, could expand the window to full view. I found the window expansion button extremely useful, but I had overlooked in my help, since I never had occasion to use it.

You notice little details like this when using the product. For example, I didn’t realize the need for a notes-only workflow in the application until I had to push all my notes through a formal minute-voting process. The application needed a streamlined way to process information-only announcements. Returning to my help, I’m now adding a workaround to the minutes process.

9. Create a User Council

At the last STC annual conference, I listened to a presentation on user councils by a writer from IBM. In her user council, she gathered about a dozen users and periodically met with them to gather feedback, test ideas, and do other mind-altering experiments (just kidding) over the course of several months for a beta product IBM was designing.

In return for their participation on the user council, each user received either a monetary sum or some other benefit. The main incentive for participation, though, was that each user had a chance to improve the software he or she spent much of their day using.

The technical writer carefully tracked all their suggestions and requests and periodically sent them responses letting them know the outcome of their feedback, whether their suggestions were used or not. This made the users feel that IBM was carefully listening to their suggestions.

If you can gather a user council, it’s an excellent idea. Often the user council is spearheaded and run by a program manager. Even if you’re not invited to participate in the meetings, you can follow the notes and other feedback compiled from their sessions.

10. Watch a User Try to Perform the Tasks in Your Documentation

Every once in a while, when someone asks if they can help me, I ask if I can watch them do the tasks in my documentation. This works well for interns in your department, or even other writers who have spare time. If you’re close with one of your users, even better.

Last year I knew one of the admins at my company who wouldn’t mind my little experiment. She asked for a tutorial on an application, and I asked if I could observe her use the help for a while. I scheduled an appointment for an hour and then proceeded to sit at a nearby chair to watch her move through the documentation. Her task involved migrating her department’s web content from single HTML pages to a new enterprise content management system.

As I watched, I realized more epiphanies in twenty minutes than I could gather from three months of editing the help on my screen. She skimmed the help while alternating her view from the screen to the help. She read quickly, and if she didn’t immediately understand, she turned to me for help. On more than one occasion, she actually put her finger on the screenshots and lists and used them to confirm her place in the help. Every five minutes, she was distracted by a phone call or a someone’s request and would have to stop the task. When she returned, she lost her place in the help.

Anytime you can borrow someone for an hour to watch them use your documentation, do it. The activity will show you the weaknesses in your help better than any other technique.

Also, observing users live is preferable to merely asking for feedback. I’ve noticed that when I give others documents to test, the feedback is usually mild. They say, “It was fine; I didn’t have any questions except I noticed this needed bold formatting,” etc. But if you watch the person, you can see their moments of struggle when they sit there trying to figure out what your document says — and where they’re supposed to click. You can see if they actually perform the task correctly as well. (You’d be amazed how people click erroneously with no idea they’re doing things in an unintended way.)

Conclusion

These ten techniques can be powerful ways to connect to your audience. It’s not always possible to implement them all, and every situation has its own needs. But I’m convinced that knowledge of user behavior is one of the most important aspects of technical writing.

Here are the ten tasks in summary. You can pin them up next to your computer and check them off as you attain each one.

10 Ways to Gather Feedback from Users

Create a Send Feedback Link in the Webhelp
Track Help Usage with Analytics Tools
Monitor Support Center Call Logs
Observe Users in Their Environment
Contact Users Periodically
Build User Profiles/Personas
Establish Regular Communication Through Biweekly Tips
Become a User of the Product Yourself
Create a User Council
Watch a User Try to Perform the Tasks in Your Documentation