Search results

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

Series: Findability / organizing content

by Tom Johnson on Sep 9, 2010
categories: findability technical-writing

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, 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 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.

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.