I'd Rather Be Writing » Kathy Sierra

Why Learning Software Is So Hard, and Organizing Content into Levels [Organizing Content #26]

Tom Johnson — Thu, 09 Sep 2010 13:57:31 +0000

In a previous post, Anne Sandstrom pointed out that NOBODY does tech writing as a hobby. Many developers program as a hobby. Engineers tinker around in their garage, building things. Other creative professionals, such as artists, photographers, and writers, paint scenes, take pictures, and write stories in their spare time. But I have yet to meet a single person who sits around writing instructions about complicated software applications as a hobby. Why is that?

One answer is that writing documentation is hard work, and few people subject themselves to laborious tasks in their free time. Often when someone does catch a sudden glimpse of understanding, stumbling into an ah-ha! moment, they document what they did for the benefit of others and themselves. We do see sites such as wikihow.com, and articles like how to Use Gmail’s Undo Send Feature. But there’s no one pushing out topic after topic of help material in the same way that people write blog post after blog post.

I think technical writing will never be a relaxing hobby for two reasons: (1) Learning complicated software and concepts is hard, and (2) Articulating complicated concepts and processes is also hard.

Tackling Too Much at Once

One reason it’s so difficult to learn software is because we try to tackle too much at one time. Our brains quickly reach their cognitive intake level for the day, and they max out. The brain isn’t used to learning so much in one day. Even if the instructions spell it out clearly for you, it’s not easy to open up a manual or a series of tutorials and plow through them for 8 hours straight, absorbing concept after concept after concept. I often give one-on-one WordPress training, and after 1.5 hours, most people have had all they can take for the day.

Let me suggest a more palatable approach to learning software. Spend about 30 minutes a day slowly ramping up on the software you use. Even if you aren’t under pressure to create anything with the software at the moment, when you spend a little time every day, figuring out a feature here and there, adding to what you already know but moving forward a few steps, it will help you learn the application in a pleasing, easy-going, low-stress way.

At work when I need a break, instead of playing ping pong, I’ll watch a tutorial from Lynda.com. Instead of chattering on and on with co-workers, I’ll search for answers to the parts of the app I need help with. I’ll spend little chunks of time over weeks becoming comfortable with an application.

I approach the writing part in much the same way. I don’t document an entire application in a day. Over the course of months of involvement with a project, I’ll document a little each day. I’ll create a few topics that reflect what I learned about the app that day, whether during my own exploration or from a meeting or other conversation. Slowly, week by week, I start piling up topics, like carrying brick after brick onto a wall, and within several months, I have a finished house.

Both writing software help and learning software are, for the most part, slow processes. When I try to zoom through either process, either the writing or the learning, that’s when the level of frustration increases.

Applying User Psychology to Help Organization

As writers, we know that we must write for an audience of users, but we often forget to craft the writing in a way that actually accounts for user psychology. It’s probably a concept that elearning professionals consider more regularly than technical writers, because they’re focused more on the transfer of knowledge than the creation of knowledge. But technical writers should also keep it in mind. It’s the concept of levels.

In a post by Kathy Sierra called The best user manuals EVER, she talks about a set of Parelli horse manuals that help the user progress by presenting information in a series of levels. Each level is contained it is own booklet. These levels motivate the user to keep learning.

Sierra says the Parelli guides present information in a series of levels

Sierra writes,

The only thing you need to know to understand the examples is that the Parelli system groups a set of skills and knowledge into “levels”. Founder/creator Pat Parelli designed levels into his program based on the success of the martial arts belt system and video game levels. In other words, he knew that the levels –key achievement milestones with clear rewards–are more motivating than just, “here you go… keep going.”

… Each “level” includes a preview book from the next level, even color-coded to the new level, that helps motivate and prepare you for moving up. The assumption–and message to the user–is, “Congratulations! You finished level one! Now look at the cool things you’ll be able to do in level two, and… let’s get started.”

… In the Parelli level two, you get a big pile of these cards, and you can customize your caribiner (hooked to your belt loop) each day with the things you want to remember, as well as tasks for that day. Each card includes a reference pointer for getting more info (which chapter of the DVD or section of the manual, etc.)

Organizing content into levels is a brilliant strategy because it considers user psychology to address learning. You don’t overwhelm the user with too much information at one time. You chunk out the learning so that it takes place over a series of time rather than dumping it all at once into the user’s lap. Because the information is spread out over a series of levels, users are more likely to absorb it.

As a user, I still like to have a reference site where comprehensive information is available and easy to search, but that’s only when I’m looking for a specific answer. When I’m trying to learn software from the beginning, I need a plan. A company that will chunk that learning into levels will help reduce frustration and move me into the power user zone much faster than the company that assumes I can read a 200 page manual in one sitting.

Blog Sponsors

Separating Basic from Advanced Topics: How Twitter Organizes Their Help [Organizing Content #18]

Tom Johnson — Thu, 08 Jul 2010 14:23:21 +0000

When you click Twitter’s help link, the help content is divided into three categories:

Twitter Basics
Something’s Not Working
Report a Violation

How Twitter organizes their help content

This division suggests a mental pattern about how people use help. You have the newbie group. These people are new to Twitter and need a grounding in the basics, such as what an @ reply is versus a dm. The content in this section, Twitter Basics, is simple and avoids focusing on the pain points; instead it focuses on the fundamentals.

The Something’s Not Working section lists specific problems users have encountered. The topics in this section are more of a random list of issues users have probably logged as support tickets.

The third column, Report a Violation, also has a surprising number of advanced topics. It’s more than simple violation reporting. More than 50 different topics are listed on that page.

Evaluating the Organization

Twitter’s model for organizing help content seems reasonable. But it fails to consider a point Kathy Sierra made several years ago in her post, The best user manuals EVER. She says that if you have a note or tip or FAQ about a specific topic, that content should be grouped in with other content on the same topic. Kathy expresses this point well through a couple of diagrams:

Group similar content together.

Keep similar content in one place.

Twitter’s help doesn’t follow this principle. Basic topics are in the Basic section — for example, How to Change Your Profile Picture or Information is in the Basic section. But a similar topic, I Can’t Update the Profile Information for My Verified Account, appears in the Something’s Not Working section. Should these topics be grouped together in one place? In other words, should basic and advanced information for the same topic be in one place?

Centralizing or Separating?

One advantage to centralizing topic content in one place, as Sierra recommends, is the search engine optimization that results. If a page has more keywords, it will rank higher in the results. A user searching for information might have better luck finding the page if the page is more keyword rich.

On the other hand, shorter topics usually have more pointed topic titles that rank higher in search results because the keywords are found in the title rather than the content body.

Overwhelming or Disappointing

Another consideration in centralizing or separating out content is whether you would rather overwhelm new users or disappoint advanced users. If you group all content together in one place, you may end up overwhelming the new user. What would normally be a simple task, such as Signing In, can have a dozen sections associated with it, if signing in happens to have a lot of troubleshooting notes and other tips, quirks, or issues. This abundance of topics can overwhelm new users and make them feel that the application is more complicated than it really is. This is one argument for separating out basic from advanced content.

However, separating out the complexity from the help will most likely disappoint advanced users who will now have a harder time finding the answers they need in the help. When an advanced user looks for help about signing in, they’ll be scattered in their search because the information about signing in isn’t in one place. The organization in the Advanced section could parallel the same organization in the Basic section, but then the advanced user would be left to guess whether the topic was basic or advanced.

From Neatness to Chaos

When you peruse the Something’s Not Working or Report a Violation sections in Twitter, you’ll see that they tend to lose their tight organization and look like a jumble of questions and problems, as shown in the image below.

Advanced topics lose their tight organization

Advanced topics tend to look this way — a loosely organized list of randomly worded topics. In contrast, the topics for the basic section are tightly organized with parallel verbs.

It seems that you can’t have both. Either you have advanced topics mixed with basic topics and end up with a semi-chaotic looking organization. Or you separate the two and maintain clarity in the help but introduce more problems with findability.

One Way to Resolve the Separation

One way to resolve this grouping basic and advanced information is to provide a list of advanced/troubleshooting topics as links in the sidebar next to the basic topics. For example, in the following topic, How To Change Your Profile Picture or Information, you could list the advanced/troubleshooting topics in the sidebar as Related Links.

Put advanced or troubleshooting topics in a sidebar as links

Twitter already does this to some extent, but the Related Articles mostly pull from the Basic section.

Conclusion

Overall, determining how to organize basic information along with advanced information poses one of the main challenges with content organization. Online platforms allow more possibilities for grouping similar content together without overwhelming the user, since you can rely on links to go directly to the content. Printed content would probably resort to cross references from one section to another. But regardless of the medium, there is no clear approach for integrating basic and advanced content.

Blog Sponsors

Seven Deadly Sins of Blogging: #1 Being Fake

Tom Johnson — Tue, 15 Sep 2009 13:45:41 +0000

I’ve decided to write a series of posts about what I consider to be the Seven Deadly Sins of Blogging (because sins always seem more interesting than virtues). Basically, I’m preparing for some presentations on blogging, and I’m hoping to get some scrutiny and feedback on these ideas. I plan to cover each one of the sins in depth with separate posts over the course of the next two weeks. My version of the seven deadly sins of blogging are as follows: being fake, irrelevant, boring, unreadable, irresponsible, unfindable, and inattentive.

Fake Hurts the Currency of the Blogosphere

If there’s one advantage blogs have over other media, such as television, magazines, and even newspapers, it’s trust, because bloggers aren’t supposed to be fake. Bloggers are usually independent voices, without financial motives or agendas. The blogger is somewhat of a free-roaming analyst, at liberty to write about any topic, from any perspective, without any obligation to corporate requirements. With such freedom, the independent blogger automatically has a certain degree of reader trust.

This sense of trust is key to the blog’s appeal. In a guest post on Problogger, Tony Hung says trust is “the only real currency in the blogosophere.” Hung explains,

At the end of the day, trust is the only real currency in the blogosphere, and people who read blogs have the expectation that they’re getting at the truth — in whatever form the truth is to them. And because there is the presumption of truth, readers will often react in an intense fashion to being manipulated, hoodwinked, and otherwise bamboozled.

In other words, the strong card that bloggers hold is a sense of trust with readers, which comes from their display of candid honesty. Readers react strongly when they find out a blogger is bamboozling them. For example, a few years ago, Edelman PR created a blog for Wal-Mart called Wal-Marting Across America that consisted of a couple supposedly traveling across America in an RV checking out all the Wal-Marts along the way and writing about their experiences. When someone discovered that Wal-Mart was paying their expenses and sponsoring the trip, readers were furious because the blog was fake.

Sharing and Trust

Not being fake is the first step in getting currency with your blog. To move in the opposite direction of fake, though, you have to share of yourself. It almost seems that the more open and sharing you are, the more powerful your posts become. For example, Stephen Fry, a writer, actor, and film director in the UK, recently wrote a semi-confessional post in which he explains how he loathes seeing some of his quotes on book jackets. Apparently one line of praise from Fry on Twitter alone can dramatically boost book sales, putting the book near the top of Amazon’s charts. When Fry tweets, he writes “completely from the heart,” one journalist explains.

You might think that a critic with such literary power would feel nothing but satisfaction and pleasure at helping promote the books he loves. And to a certain extent Fry does. But in this post, Fry also shares another side of his feelings. He jokes with his literary agent that he will make a public confession that he hasn’t read any of the books for which he supplied quotes:

The plan, as I told my agent, was to make this confession as a way of getting publishers off my back. It may sound ungracious, but I get asked so many times a week to read book and supply quotes for them that I’m getting a bit fed up. Not because I don’t like reading, nor because I don’t like being sent books, though mostly of course, I am sent proof copies rather than the finished article. No, what I’m fed up with (and it is my contention that I am SO not alone in this) is seeing my name on the fronts, backs and flaps of books saying things like “a beautifully paced, unforgettable thriller”, “a magnificent feat of imagination”, “a delicately realised and vividly felt journey through memory and desire”, etc etc. Yuckety, yuckety, yuck. Pukety, pukety puke. (“Don’t Quote Me“)

The more you’re open, transparent, and sharing on your blog, like in this post from Fry, where he shares his real thoughts, which may be a little surprising or startling to some, the more trust you engender with your readers. We love Fry even more because of this post (and consequently, I’m guessing he’ll be in even more demand for book quotes).

For another example of a post that shares personal information with influence, read this mind-blowing post from the always fascinating Penelope Trunk: How to Decide How Much to Reveal About Yourself. She shares so much it nearly crosses boundaries, but the effect? Nearly 350 comments on the post from engaged readers.

Insurmountable Challenges from Corporate Bloggers

Independent bloggers may find that trust and personal sharing come easy. But corporate bloggers who write about their company’s products or services have nearly insurmountable challenges when it comes to trust. A corporate blogger struggles against the “used car salesman situation”: no matter what the salesman says, you really don’t trust him. If he praises a car on his lot and recommends that you buy it because it’s a great deal, uhm, yeah, you don’t believe that because the salesman’s agenda is obvious — he wants to sell you a car. There’s no trust.

Corporate bloggers have the same problem. As a reader, you may not believe the blogger because of the obvious agenda. But it’s a damned-if-you-do, damned-if-you-don’t situation. If corporate bloggers praise their company’s products or services, we don’t believe the blogger. If corporate bloggers disparage the products or services, we perhaps believe the blogger, but this may be damaging to the company’s product or service. And most likely the CEO won’t allow negativity posts. However you look at it, trust is an issue that permeates corporate blogs.

According to research from Forrester on corporate blogging, Josh Bernoff says that “only 16% of online consumers who read corporate blogs say they trust them.” And those same 16% pretty much trust everything. Because of this distrust with corporate bloggers, Josh concludes:

If you blog, your goal should be to create a blog about which people say “I like that – I don’t think of it as a company blog.” For the most part, that’s a hurdle you need to jump to gain their trust. I don’t mean to hide who is writing the blog. I mean it has to be more about your customers than it is about you. Blogs exclusively about companies and products are what I think generate these low trust ratings. So don’t do a blog like that.

Kathy Sierra also recommends a similar strategy: “With a few exceptions, the worst mistake a ‘business blog’ can make is to blog about the business.”

Essentially, the strategy of the corporate blogger, then, should not be to focus on promoting his or her own company’s products or services so much, because the blogger has no trust with these topics. The agenda is too obvious, and the blogger lacks currency. But neither should the blogger completely dismiss the topics either, because then the blog ceases to be relevant to readers (sin #2).

Instead, according to Bernoff, the corporate blogger should focus on the company’s customers, their problems, their successes, their questions, and perspectives. As corporate bloggers shift focus away from a marketing mindset, they will begin to develop relationships with their readers, and those readers may start to feel trust.

Bernoff says Rubbermaid’s blog does a good example of focusing on the customer more than Rubbermaid. However, I’m not really into Rubbermaid, as adventurous as organization can be. A more relevant example in tech comm is Techsmith’s Visual Lounge blog. Once a week, they showcase videos created by people who use Camtasia Studio. By focusing on user videos, they aren’t so much shining the spotlight on themselves as much as their customers. Not all the posts have this focus, though. That’s okay, because although user problems and solutions are intriguing, a blog can also succeed by establishing relevance with readers.

Palimpsest from Sarah O’Keefe and The Content Pool from Alan Porter are also written by “corporate bloggers.” But with each of these blogs, I don’t think of them as company blogs. I think of them as blogs written by industry experts. This is partly because their posts rarely promote their company’s products and services.

In the spirit of transparency, you should know that TechSmith, O’Keefe, and Porter all advertise in the sidebar of my blog. And I’m presenting at a conference sponsored by WebWorks. Does that conflict of interest perhaps remove some of the currency of my recommendations? In a way, yes — even though what I’ve said is perfectly true.

Blog Sponsors

IT Author Podcast — Two Podcasts on Flare, One on the Making of a Technical Writer, and a Dogcast on User Psychology

Tom Johnson — Mon, 12 Nov 2007 06:11:04 +0000

I listened to Alistair Christie’s IT Author podcast the other day online and then later driving home from work. Alistair is based in Scotland and has one of the most enjoyable podcasts on technical communication around. If you listen to podcasts, add his podcast to your feed. His latest episodes are as follows:

In Flare: the good stuff, he explains the features of Flare that he really enjoys, such as being able to integrate his own javascript and PHP scripts directly into the code.
In Why do we use Flare?, he and a colleague talk about Flare in depth — for about an hour, actually, discussing the little things that annoy them about Flare, such as the visual editor.
In What does it take to be a technical writer (a carcast), he mentions some key qualities technical writers need, such as a curiosity for learning and understanding how things work.
In his May 19th Dogcast, he actually gives the podcast while walking his dog. The podcast covers the evolution of help, the need for technical communication, and user psychology.

Although the dogcast started out slow, this was the podcast I enjoyed the most. About 15 minutes into the podcast, he really hit his rhythm and started driving down into the topic that seemed to grip him most: user psychology. Users don’t read manuals. The days where long, printed manuals were standard prerequisites to using technology are gone. People experiment with an application and try to learn by doing; when they need information, they search for information about the task they’re trying to accomplish in that instant. Online help is critical in helping users find a single piece of instruction for an immediate need.

Users are also in a state of anger and impatience when they turn to the help. They’re mad because the software has frustrated them and stopped their work. They don’t want to read a manual. What they really want is someone to explain to them how to do something.

Listening to Alistair’s thoughts on the user’s state of mind made me think about the help we write. Why is it that we often begin a software documentation project by documenting all the tasks that users can possibly do from all the available functions of the software application? We spend the bulk off our time creating written instructions that almost no one wants or reads.

Instead, I think we should be focusing on several key deliverables:

Audiovisual tutorials or screencasts
Short getting started guides covering the basics
Context-sensitive online help

Further, we should begin by getting to know our user — not through a description from the SME or business analyst, but actually contacting the user to determine the tasks they want to accomplish and the format for the help.

The Getting Started guide should walk them through the most common, basic tasks the user will need to perform. This guide should be easy to get through. Alistair says the help should provide immediate rewards to the user. Take them through some quick wins. In the Getting Started guide, you give them easy-to-perform tasks that make them successful.

The screencasts (which should also be short) provide a range of other benefits, such as providing the experience of a friend showing them how to use the application.

The context-sensitive online help gives the user immediate information about the task at hand. The online help also provides a searchable database for answers.

So often we begin with the comprehensive manual in mind, when that’s the last priority for users.

Additional Resources

A few months ago I posted some notes from a Kathy Sierra presentation that talked about the user’s state of mind as well.