Making Help Content Enjoyable to Read — Impossible Quest?

In my previous post (“Less Text, Please”), I argued that users want shorter texts. I also explained how social media and Internet sites have possibly rewired our brains to incline us toward shorter content — according to some, our gnat-like attention spans can only consume a few short paragraphs before tapping out. The Onion has a great parody of how a single block of uninterrupted text causes mayhem for readers (“Nation Shudders at Large Block of Uninterrupted Text”).

But while short texts are met with smiles and cheers, many of my blog’s readers suggested that raising up a standard of brevity may be misguided. In fact, in many contexts, readers don’t mind long texts. What readers truly want, they explained, is simplicity, and simplicity is not always achieved through brevity.

As long as we strive for simplicity, illustrate our ideas, and focus on business relevant content, perhaps even the most technical user’s guide (such as a Network User’s Guide, shown below) might become as pleasing to read as a novel.

Is it possible for help content to be as pleasing to read as a novel?

Is it possible for help content to be as pleasing to read as a novel?

(Drawing based on a photo of Clark Gable.)

Reading Modes

First we must distinguish between two critical modes of reading: reading to do and reading to learn. The distinction between these reading modes is an idea from Ginny Reddish (which Caroline Jarret expands on here). If you’re reading to do, you’re searching for an answer to a specific question.

Here’s an example of reading to do. You’re giving a presentation using PowerPoint, and 10 minutes before your presentation, you’re trying to figure out how to separate your slide notes from the projected slide display. In this scenario, lengthy help text is your enemy. You want the answer in as brief a space as possible, and as quickly as possible. You’re reading to do.

Ginny explains this mindset in one of her slides:

Ginny Redish -- reading to do

From Ginny Redish — reading to do

(See “Understanding Web Readers (and Non-Readers) — Creating Usable and Effective Web Content.”)

I’m sure you can guess which guy in the above slide has a PowerPoint presentation in 10 minutes. But consider this other learning scenario. You know you need to improve your presentation abilities, and you’re tinkering around with Microsoft PowerPoint. There are so many buttons and features on the ribbon. It’s really overwhelming. You’re not looking to learn a specific feature, just the tool in general. You may have set aside 20 minutes a day to learn PowerPoint. In this case, you’re reading to learn.

Help content will never approach novel-like pleasure reading when a user is operating in the first mode: reading to do. But in the reading to learn mode, there is potential for something other than the frantic, frustrated help-cursing mode.

In Reading to Learn Mode, Length is Irrelevant

Let’s stay in the reading to learn mode. As long as the content is business relevant, entertaining, and simple to understand, there’s no reason to doubt the reader’s ability to become immersed in the content for long periods of time. Length becomes much less of an issue in this mode.

I don’t have hard evidence for assertions about length, but in Wired, Clive Thompson notes that the most popular blog articles are about 1,600 words per post (“Clive Thompson on How Tweets and Texts Nurture In-Depth Analysis”). This is about a seven-page essay. Writer/editor Tim Rich notes an eye-tracking study from Poynter showing that users skim until they find relevant content, and then they read for longer periods of time. Many other readers tell me they regularly consume long novels, and even wish the novels were longer.

Clearly in some contexts, length is not a problem. When content is interesting, you can have it any length you want. In one of Tim Rich’s posts, he quotes comedian Jerry Seinfield, who says, “There is no such thing as an attention span. People have infinite attention if you are entertaining them” (“Attention Spans”).

I think most will agree that text can be long and still be acceptable to readers. However, the real question is whether help content can be long and still be acceptable to readers. If not, why?

Is the Genre of Pain an Exception?

Let’s consider a basic reality. Help content is in the genre of pain. It’s right next to the tax code, your car manual, and a trip to the dentist. But does help always need to be trapped into a category of boring text no one wants to read unless they absolutely have to? Must it always be on par with a trip to the dentist?

Going along with the dentist metaphor, can the dentist ever change the experience so that you actually prefer to lengthen the visit? His fundamental activities, drilling, sticking his hand in your mouth, doing painful things to your teeth — it’s never something you want to prolong. Just like the tax instructions, no one wants the experience to be any longer, for goodness sakes. The last thing we want to do is extend the pain, right?

But Shorter Does Not Mean Less Pain

Although we do not want to prolong the pain, shorter is not always less painful. In fact, sometimes brevity increases pain. Imagine a tax booklet instruction that was just two paragraphs long. To the accountant writing the instructions, trying to keep it “as simple as possible, but not simpler,” as Einstein says, he or she may look at the concise set of instructions and feel satisfied. But this concision will likely leave me in the dark. I’ll end up scratching my head trying to understand terms, wondering if I’m interpreting it correctly, wishing there were some more examples and clarification. The time I save with shorter text is balanced by increased confusion time afterwards.

What we really want isn’t brevity. What we want is simplicity. As Whitney Quesenbery points out, “the repeated complaint about ‘too many words’ isn’t really about the word count, but about the density of the information and how this makes us feel about the information.”

When you hand users a two-page quick reference guide, their faces light up with excitement because they think the application must be simple. Project managers are cheering as well because the brief instructions seem evidence of a simple application, which means they did something right.

A sample quick reference guide

A sample quick reference guide. Users assume shorter means simpler, but that’s not always the case.

But in reality, a two-page instructional document (such as the one on the right) for a complicated application may only leave users confused. As users make their way through the quick reference guide, they may encounter even more frustration than they would with a longer guide.

In a world of extreme concision, the novice user may be especially lost, like a hiker with a dim flashlight trying to navigate out of a rough patch of woods. The dim flashlight may be small and easy to carry, but in this situation wouldn’t the hiker prefer a larger floodlight instead?

As I said, what users really want isn’t brevity or shorter texts. They want simplicity. Who wouldn’t mind a 20 page guide if it were full of clarifying illustrations, examples, screenshots, and maybe even a glossary?

Illustrations and Simplicity

If simplicity is the goal, not brevity, you can implement a variety of techniques to simplify concepts. One of the most important strategies will be illustrations. Nothing clarifies a concept more than accompanying it with an illustration that drives the point home.

Before I push illustrations too much, let me start off with a caution raised by Tim Rich. Rich says,

There are times when a striking image expresses something in a more powerful or accurate way, but there are also countless occasions when words are an extraordinarily moving or precise media, when words can do more, say more, show more or achieve more (“On Pictures and Prose”).

In other words, images are often overrated in their ability to communicate information. A well-written paragraph full of description can sometimes communicate more information than an image. But without getting into semantic contests between text and images, I think we’ll all agree that combining the two is almost always a winning strategy. To keep the reader’s attention as you move through concepts and strategies, insert a concept diagram on every page, separating blocks of text.

A concept diagram explains a concept visually rather than merely decorating the page with a pretty picture. The concept diagram reinforces an abstract idea through visual means. Here are a few sample concept diagrams from Robert Horn’s Visual Language: Global Communication for the 21st Century (p.60).

Concept diagrams from Robert Horn's book on Visual Language

Concept diagrams from Robert Horn’s book on Visual Language

As you can see, you don’t need to be a great artist to create a concept diagram. All you need is some basic graphics abilities and an idea of how to communicate your ideas.

If illustrations are so helpful in simplifying concepts for users, why don’t more technical writers illustrate their help? Several reasons:

  • Lack of graphic design skills (or feelings of inadequacy in a world of professional expectations).
  • Lack of conceptual material to illustrate (it may all be procedural).
  • Not enough time to create the illustrations you need.
  • Difficulty in coming with a clever way to depict an abstract idea.

All of these reasons contribute to a text-heavy help. But if writers were to focus more effort on illustrating help content (and not in an Ikea-like way), you would see a complete turnaround in the reception of help content. Length would become less of an issue, and readers would welcome help content openly rather than resisting it at every level.


Illustrations aren’t the only solution to helping users learn a complicated process. Videos are also key. A simple screencast takes just several hours to produce. The dynamic visual interface combined with your human-narrated voice can have a powerful influence on user learning, since it allows users to see tasks in the context of an interface.

I’ve written about screencasts and voiceover techniques at length on my blog, so my purpose here isn’t to explain techniques, but merely to suggest that writers include more screencasts. Screencasts should be a more common deliverable than they currently are. Right now, based on my interactions with other professionals, I’m guessing only 1 in 10 technical writers creates screencasts, even though screencasting software applications such as Camtasia Studio or Jing are simple to learn and use.

Relevant Content

Another element required to convert help into a more pleasing reading experience is to focus on relevant content. A lot of times, we technical writers explain how to use a software application, but we leave the details of the particular business context alone. I know that when I worked as a technical writer for a financial firm, I rarely wandered into business context and use, preferring instead to merely describe how to do various functions in the application.

Why didn’t I describe more of the business use? Financial analysis is complicated, and uses are multiple. I clearly ran into the edge of my knowledge of the subject matter and didn’t feel comfortable getting into more in-depth business strategies and uses.

However, often the business context is more important than mere how-to within the interface. Many users, especially tech-savvy ones, can get the hang of an application easily enough. Look at even the simplest of apps out there — Facebook and Twitter. People aren’t clamoring for instruction on how to post updates to these web applications. Instead, users are confused about how or why they should even use the applications at all. In what contexts would they be useful or strategic? Why is it that nearly everyone has a Facebook account, but only a fraction of these people actually uses Facebook? Same with Linkedin and Twitter. The instructional material about business use and strategy is perhaps lacking (or unpersuasive).

Most help material has the same problem. The writer explains how to run a report, for example, but doesn’t say why the report might be useful, or how you might interpret the report, or who would be the most relevant audience for the report.

As another example, look at Google’s Chrome comic documentation.

Chrome's comic documentation failed for me

Chrome’s comic documentation failed for me because it lacked business relevant content.

When this first came out, it looked cool. I tore into the first few pages with a new-found enthusiasm, because this format seemed to open up documentation into a world where it was fun and fresh. But after about five pages, I lost interest, as did many other people who started reading it. It seemed to get boring and somewhat irrelevant, as well as technical, and so I clicked elsewhere. A cool idea, still, but perhaps not enough focus on business relevant content. (By the way, I have not seen Google produce any more comic documentation since then.)

There’s usually an entire dimension to help authoring that is missing from most help material: help about the business context and use. That’s the manual I would pay for, not the simple how-to about tasks already intuitive in the interface. And when you start delving into relevant business content, you have the power to keep a user’s attention at length.

Conclusion and Disclaimer

I’m not saying all help material needs illustrations, screencasts, and business relevant content, because every application or project is unique, and clearly generalizations don’t always apply. But as a guideline to follow, help could be a lot better if it more often contained these elements.

If you do include illustrations, screencasts, and business relevant content, you might not need to worry so much about brevity and word count. Your users won’t glance at a giant block of uninterrupted text and throw up their hands in exasperation. They may even start reading page after page with interest, forgetting about the time or page number.

Madcap FlareAdobe Robohelp

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.

  • Patty Blount

    I’ve been following the discussion on this topic closely because it intrigues me. Is internet technology really producing a nation of “flitters”? I hope not, but yet, as I commented in the original post, I see it happening to me.

    Making content – ANY content – enjoyable to read should be our goal as tech writers. Consider the popularity of the Dummies books. What other technical information has enticed readers to not only buy, but read cover to cover?

    I liked your point about pain, and how shorter does not always mean less pain. In my comment on your original post, I described having to study two B.O.S (Business Operating Systems) manuals to learn how to create reports. This was because the manuals were not designed to be task-oriented. I had to first locate the information I needed, then distill it into a series of steps.

    The information was organized into two uninterrupted blocks of text – one was a conceptual explanation, and the second was a high level procedure located elsewhere in the manual. The second guide was an alphabetized list of the commands and their syntax for performing the procedure. If I were to print out all that information in a single run, it would have been perhaps three pages.

    I didn’t know it then, but this experience shaped me into a technical writer. I complained about the lack of cross-references or index entries. I wished for examples that illustrated how the command syntax should look in “real life.” I wrote my own tasks based on the results of my studying so the next person wouldn’t feel my pain. (See what I did there? *grins*)

    This is why, over 20 years later, I can still recall it.

    • Tom Johnson

      I liked reading about the formative experience that inclined you toward technical writing. Thanks for sharing.

      You also wrote, “Making content – ANY content – enjoyable to read should be our goal as tech writers. Consider the popularity of the Dummies books.” I think too often we forget this aspect in what we create — at least I do. I tend to be more focused on information accuracy and clarity and organization, without considering whether it’s enjoyable to read. That’s partly why I wanted to address this topic — reading enjoyment seems to be a huge hole in help materials.

  • Christine Astle

    I totally agree with you about the relevant content. Personally, I think the future of technical communications is not just the generic how that tends to be the staple of tech comm, but the why and the what and the how in that particular user’s context.

    I think if the information is relevant, well organized and well written, the length is less important — as brief as can be while still being complete and clear.

    • Tom Johnson

      Thanks Christine for your comment. I think relevant content is one of those big topics in tech comm that we often avoid (myself included) because it can be really difficult information to get, especially if you’re not a user of the product. But I want to move more in this direction.

  • Avi Solomon

    Great points Tom! At the bare minimum introducing step-action tables (technically a diagram) can frame the material and improve comprehension. The ability to make Visio diagrams and produce Camtasia screencasts are essential for any tech comm strategy and career to succeed.

    • Tom Johnson

      Thanks Avi. I’ve never heard the term “step-action tables,” but they seem like a type of diagram. Or is it just a text workflow? Either way, it’s probably a good thing to include rather than just straight text.

  • Melanie Blank

    Yet another terrific post, Tom – thanks! (And thanks for the links; loved the “Onion” article…)

    This paragraph (and the two after it) really jumped out at me:

    “What we really want isn’t brevity. What we want is simplicity. As Whitney Quesenbery points out, “the repeated complaint about ‘too many words’ isn’t really about the word count, but about the density of the information and how this makes us feel about the information.”

    But, how simple can you make user documentation when you’re dealing with an overly complex, feature-laden software application (with a not very intuitive interface)?? I’m struggling with that now.

    As a boss of mine a no. of years ago said: “Clean documentation cannot fix a messy system.”


    • Tom Johnson

      Thanks for your comment, Melanie. I think that with a complicated application or system, the only way to make it simple is by creating a longer text that provides more illustrations, examples, maybe some embedded videos, and other elaboration.

      My basic premise, which you pointed out, is that sometimes to make content simple, we have to avoid brevity, even if the reader’s initial reaction is “oh wow that’s long.” I think as users move through the document (assuming it’s well-written, illustrated, etc.), they’ll experience less frustration than if we were to compress it into a one pager and try to pretend that they can understand it all with a quick glance.

      • Melanie Blank

        Thanks for the additional comments, Tom. :)

      • Michael O’Neill

        IMO: I think information density is the crux of what you’re getting at. It’s very easy to pack a lot of detailed information into a page. But we know that this quickly becomes very difficult (if not overwhelming) for readers to use. Even for users already familiar with the subject, it often demands a lot of attention to cognitively/conceptually unpack the dense material.

        As technical writers, we have some informed theories and approaches to help. These may increase raw page count, but it makes the information much more accessible and usable (perceived as shorter/simpler). Information chunking, breaking information into task, concept, and reference types, use of lists and whitespace, introducing context sensitivity, etc… all fit in to our bag of tricks.

        And sometimes your subject is just going to take a lot of space to write about. I find this particularly true when describing concepts (Why would I use this?) etc… Use of technical illustrations, etc… can help there. But I think Tom is right on track by attempting to kill the myth that users won’t read. Users will engage and read provided that the information they get is relevant, accessible, and usable.

        Just my 2 bits…


        • Tom Johnson

          Michael, it’s interesting that you compare the read to learn and read to do breakdown against DITA’s task-concept-reference structure. Setting aside the reference category, does “read to learn” = concept and “read to do” = task? This would be an interesting idea to explore. Does a reader even need this division? This is certainly a key strategy in organizing content. Thanks for the comment.

        • Michael O’Neill

          Good question, Tom!

          You know, I don’t have the references to look up actual dates right now, but I can say that I was actually not referring to DITA at all. The notion of three main content types (concept, reference, task) has been around for a long time…well before DITA. I had just assumed (or read someplace) that they put Darwin in DITA because it’s an _evolutionary_ approach that builds off of established/known practices of information typing in tpubs as opposed to a new and revolutionary approach that says, “Hey, everyone should do it in this new, unique way!”.

          > why does DITA break these two apart? Why not explain the concept and then list the various tasks below this conceptual explanation?

          I can’t speak for DITA. But you can still maintain your information types on one “page” if you want. I don’t think they need to be separate at all. The problem, imho, is when you start mixing everything together in one paragraph or “essay”. Users have to read the whole thing to find the information they want and don’t produce something that’s easy to scan, navigate (usable).

          Personally, if the entrance to a help topic is from a window in the app (context sensitivity), I will often break a page down like this:

          * Conceptual info. What types of things you can do here, etc…
          * Screen shot (yeah, contentious issue, I know…but my personal take on it is it helps with whitespace and helps people quickly identify relevant content when they are coming back to the docs/browsing)
          * Reference material (if there’s a need to describe actual buttons on the app window, that can go here. If there’s no reference information needed, the section on the page can be omitted)
          * Tasks/procedures (how to use the the software to achieve your objectives)

          > Why not explain the concept and then list the various tasks below this conceptual explanation?

          That’s pretty much exactly what I do (see above). We don’t use DITA OT or anything like that, but we do have a pretty clear information architecture that separates content types.

          In the end though, I use the information architecture I do because I’ve had good results from it (as far as user feedback). We can pick it apart, count the ways it is wrong, celebrate it or curse it. In the end, it’s all about how it works for your audience.


          PS: This is really a fascinating discussion. I hope it keeps going and some of the DITA crowd pipes up!

  • Michael O’Neill

    Hi Tom!

    Great post, as usual. I think your delineation of content into procedural/task and concept is nice. If you just add “reference”, you just defined the three primary types of content.

    Personally, I’ve found one simple characteristic behind every piece of help content that I’ve enjoyed reading: it made accessible information that I could use to act on. It’s surprising how often something so simple is missed…


    • Tom Johnson

      To follow up on this thread with the task versus concept, exactly why does DITA break these two apart? Why not explain the concept and then list the various tasks below this conceptual explanation? Or is it just that the structure of the XML tags separates the concept into its own document? I’ve read a bit about DITA, but I never understood the why, just that there is this division between task and concept.

      • Michael O’Neill

        > exactly why does DITA break these two apart? Why not explain the concept and then list the various tasks below this conceptual explanation?

        I’d really like to hear a DITA practitioner chime in here…

        I do it because it makes for more accessible and usable assistance (IMO). One book that you might want to check out that talks a lot about information architecture using task, reference, and concept blocks is the latest edition of _Establishing Quality Technical Information_. Don’t be put off by the fact that it’s published by IBM. It’ll give a rock solid foundation for a lot of the concepts that ultimately wound up informing DITA…but also that underly much tech writing “best practices” (whatever those are)…

        As I indicated, I think leading with conceptual information and following with task is fine. If your concept is big enough/more like a small white paper, then it’s probably it’s own thing and doesn’t share “how to” information.

        Regardless, I think the important thing to remember is this: follow “rules”/recommendations only insofar as they help you to produce the type of assistance your users can actually use. There’s nothing stopping you from doing your own thing, innovating a completely new way, or sticking to how they did it 30 years ago (providing your users find it optimally helpful and it’s doable and maintainable from a writing perspective).

        OK. I’m rambling. Long day, not enough coffee.



  • Ramakrishnan

    As in a typical tech. doc. setup, we explain the concepts specific to a window followed by the tasks that can be performed using the window. The other day, while reviewing a chapter, one of our product managers wanted to check how the tasks have been explained. For that, he said, he had had to wade through all the content (some windows needed about 4 to 5 pages of concept to be explained) before jumping into the Tasks section. He then asked “Can we have a separate reference guide or something that only explains the tasks? For the first-time users, the concepts are OK, but for experienced users, why can’t we provide a tasks-only guide too?”

    In essence, he wanted a DITA kind of setup, where content and task can be separated. With DITA’s information typing model, we could produce just about any kind of deliverable: fully fledged user manuals (concepts followed by tasks), concept-only “What is this window all about?” guides (can be used by the Marketing and Sales people to make proposals), and task-only “How to?” guides.

  • Christine Astle

    I think that Ramakrishnan has it right. I’m not a DITA expert but when you separate concept from task from reference, you can combine those in different ways, depending on the output, the context, the audience.

    And depending on the technology you have supporting it, you can combine them in different ways within a single help system. For example, you can just show the concept and task that’s relevant to a particular screen or you can allow the user to walk through all the concepts that apply to the larger, complex procedure.

  • Pingback: A technical communicator’s history lesson « Write Trends()

  • Jonatan Lundin

    I’m a DITA practitioner who is also involved in the development of DITA (DITA machine industry sub-committee). I argue that DITA has brought a lot of good things to the tech com community, but I also agree that there are “holes” in the architecture that means that DITA is not giving the full picture you need as a technical communicator. For example:

    •Hot do we identify the meaningful type of content that end users need?
    •How shall the identified content be organized to be searchable?
    •Etc, more questions are given at

    As you can see, DITA do not give any answer the questions and according to me it is not in the scope of DITA to give answers. There are a lot of principles, philosophies, ideas and methodologies (user centered design, task orientation, minimalism etc) available as a complement to DITA, but I have found them to be too shallow; when it comes to the practical work of documenting a technical product, the existing design philosophies just make us ask more questions than they provide answers to.

    Also, when working in a documentation project with tight schedules there are not time to spend on developing answers. Of course a content strategy developed in an information analysis project prior to start documenting a product is needed.

    I’m working on a concept called SeSAM which has several purposes, but the most important is to provide technical communicators with a framework that helps them identify and organize content to make it searchable. SeSAM start off from several view points, and the most fundamental is that users are searching and goal driven.

    The minimalist philosophy states that the user is active when using a product. Users are using the product based on prior background knowledge (“hey, if I try to do like this the product might work”). Users are also lazy in a sense where they want to put in as little energy as possible to reach a goal.

    When the prior knowledge is not sufficient, a user tries to find information elsewhere and at a certain point a manual is used. Based on this assumption you can elaborate search situations. SeSAM includes eight search situations (see and they are developed to be generic, meaning that they are not targeting a specific type of technical product.

    The idea is that a user located in a search situation shall be able to identify the situation in the manual and be guided to the part in the manual that gives the answers. Content is built around “Meaningful result statements (MRS).

    When a user is searching for something there are several facts to consider: First the user might be helped if s/he understand what type of content is available in the manual. Then given that the user has this understandment, s/he wants to know where in the manual a specific info is located. This assumes that the user can express what s/he is locking for.

    Thus one of the hypotheses with SeSAM is that it becomes much easier to find information if the user is aware and understand the logic and principles behind what type of content is available and how it is organized. Sort of standardizing the content architecture.

    DITA assumes that you start to develop task topics, but a user is doing a task to reach a goal. So we must look beyond the tasks and identify what goals the users are trying to pursue.

  • Jonatan Lundin

    I’m a DITA practitioner who is also involved in the development of DITA (DITA machine industry sub-committee). I argue that DITA has brought a lot of good things to the tech com community, but I also agree that there are “holes” in the architecture that means that DITA is not giving the full picture you need as a technical communicator. For example:

    •How do we identify the meaningful type of content that end users need?

    •How shall the identified content be organized to be searchable?

    •Etc, more questions are given at

    As you can see, DITA do not give any answer the questions and according to me it is not in the scope of DITA to give answers.

  • Beka

    I’ve always been an advocate of the K.I.S.S. theory. But after seeing your post, I’m now starting to realize that it shouldn’t always be the case. This blog post is the perfect example. It’s lengthy but it gets its job done. Oh, and the illustrations helped a lot.

    But if I’m reading just because I have nothing else to do, simple works best. For example, I’ve never enjoyed the LOTR novels because of the complicated writing style.

  • palm beach clerk

    My spouse and i still can not quite think that I could be one of those reading the important recommendations found on your web site. My family and I are sincerely thankful for your generosity and for presenting me possibility pursue this chosen career path. Thank you for the important information I acquired from your web site. cpa palm beach