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

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.

Adobe RobohelpMadcap Flare

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm interested in topics related to technical writing, such as visual communication, API documentation, information architecture, web publishing, JavaScript, front-end design, content strategy, Jekyll, and more. Feel free to contact me with any questions.

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

  1. Greg DeVore

    Great post Tom. Too often as technical writers we are like a first date that wants to tell you their entire life story. You may be interested in that much detail at some point, but not yet. Users usually want enough information to accomplish some basic tasks that will help them decide if they want to dig deeper into the product.

    Great example on content organization. That is something we definitely need to consider more as the documentation for our product grows.

  2. LeeAnn


    You make a lot of valid points in this entry. I’m a writing student who is highly interested in pursuing a career in technical writing after the completion of my degree. I have noticed that many of my fellow students write within their chosen writing field areas in their spare time, even amidst all of the work we have in our graduate program. Particularly, the creative writers are always discussing the novels, short stories, and poems they worked on over the weekend. Writing is definitely a hobby for most of my classmates, and while it is to a lesser extent for me as well, I also spend a lot of my free time doing research online and playing with websites and software. In this way, perhaps those of us who are either already technical writers or who are interested in becoming a technical writer do actually, in a sense, pursue technical writing as a hobby as well as a profession. After all, how many times have you, for example, joined a website with no intention of creating a serious product by using the site, but simply because you were interested in how it works? Because part of the technical writing process includes knowledge accumulation and system building, I think that you are participating in technical writing as a hobby when you actively seek out new technical knowledge. You’re just not completing that final step of committing to written words what you’ve learned so that others can learn it too – though, if you’re like me, you probably end up eventually teaching your friends and family how to successfully use a program or navigate a site anyway.

    On another note, I wholeheartedly agree with your advice about completing both learning and writing in small chunks rather than in one large swoop. I think that 1.5 hours at a time is probably the absolute maximum for any learning situation; after all, most college classes (and high school classes that are on the block schedule) last for approximately 75-90 minutes. Any more time than 90 minutes and students can become antsy, distracted, exhausted, and overwhelmed. My graduate classes are 2 hours and 45 minutes, but professors always give us one or two longish breaks during each class. That being said, at least in my own experience, the advice that you give about learning in 30-minute intervals is right on target. I work best at home by learning or writing in half-hour increments, taking 15-20 minute breaks in between to eat, shower, do chores, play around online, or watch the news. If writers follow your advice, I have no doubt that they will find themselves becoming more successful (and more enthusiastic!) learners.

    Finally, I absolutely love the idea about including levels, especially pretty color-coordinated levels, in manuals. That’s why a lot of video games are so successful… I mean, when I think about Galaga and Dr. Mario, which are quite possibly two of favorite games of all time, I think of the ascending challenges in each level. If these games were just one big jumbled cluster of challenges that kept increasing without breaks or level-to-level movement, there would be no markers of accomplishment. That’s part of what keeps players coming back to the game; we want to get to as high of a level as possible because it makes us feel good about our mad playing skillz. This strategy is just as brilliant in technical instructions as it is in video games; learners want to feel a sense of accomplishment by completing a level and the potential challenge in mastering the following levels. The inclusion of a preview of the next level also makes a lot of sense, because it piques the learner’s interest and gives him or her something to anticipate. And the more interest someone has in a subject, the easier it will be to learn.

    Thanks so much for writing this entry – and for having such a helpful, comprehensive blog on technical writing. I have already bookmarked your blog and look forward to reading more!

    LeeAnn E.

  3. matthew

    FYI, here’s an example of tech writing as a hobby. This was produced by a group of amateurs collaborating in their free time: http://ubuntu-manual.org/

    I have no connection to the manual project, but I do have a free-time connection to Ubuntu. In my day job, I’m a tech writer for a biotech project.

  4. don don

    Very thoughtful observation, Tom.

    Here’s my take. First, software, especially consumer software, must be simplified without the expense of core capability/functionality. The simplification may be manifested by super user friendly UI by default and in the meantime, providing an easy way (Settings) for a user to advance to advanced functionality when a user is ready…

    Secondly, on the documentation part, the layered levels are an excellent idea and it has been implemented by experienced software developers or technical writers already. Here’s an example,

    Section 2, namely, “Navigation of this Document” reflects this approach. It’s a no-brainer.


    1. Tom Johnson

      Interesting example. I don’t really see how the information is layered — it seems like it uses jump links to allow quick navigation. But then again, I looked at it fast. Re simplification, I agree. Leo Dell’s talk at the last STC Summit was all about that principle. Check it out if you have access.

  5. Jim Campbell

    Hi Tom,

    I just wanted to write and let you know that, from my experience, I see a wide range of people who do technical writing as a hobby. For example, this entire XML-based documentation syntax ( http://projectmallard.org/ ) was developed for the GNOME documentation team almost solely by one person, Shaun McCance. Shaun and I shared details about the project as part of the project showcase at this past Spring’s WritersUA conference in Seattle. The project was warmly received, even by avid DITA fans.

    As a note, GNOME open source documentation is translated by volunteers into over 80 languages.

    Also, although DITA is currently only packaged in one primary Linux distribution (OpenSUSE), there are a good number of technical writers in the open-source community that are very skilled with DocBook, XSL, Xpath, XQuery, FOP, and other XML technologies.

    Oftentimes these same contributors have day jobs that are entirely unrelated to how they contribute to their projects. While it’s true that some of them are programmers or physicists, others are lawyers, students, or (in the case of me) involved in Human Resources.

    Feel free to let me know if you have any questions about any of this. :)



Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>