Incorporating Learning into Tech Comm Deliverables

I recently attended an internal conference at my work for instructional designers. The focus of the conference (as I assume the focus is for many instructional design conferences) was on “learning.” I always find the emphasis on learning in the ID crowd fascinating, because this is rarely a word that tech writers use, yet our goals are largely the same.

An action-based model for learning

The keynote speaker presented a model for learning that included five steps:

  1. Act
  2. Reflect
  3. Learn
  4. Plan
  5. Anticipate

The Plan and Anticipate steps seem nearly the same. And I’m not sure step 3 is legit, because how can “learn” be a step in “learning”? But stick with me, because I really like the first two steps.

The speaker explained that this model of learning focuses on “action-oriented development.” He admitted his bias about the importance of experience in learning. He also emphasized that unless we take the time to reflect on our actions, we don’t often learn from our experiences.

Given that I don’t include any activities for acting or reflecting in my help material, I mulled over this model for quite a while. By not incorporating these elements, am I excluding what would otherwise allow my users to learn? Why isn’t learning a more important consideration for the way I develop my help material?

Attempts at Integrating These Elements

While I was about on lap 20 at the pool the other night, I realized how to integrate both the action and reflection components into help material.

The first component, Act, can be incorporated by including some sipmle practice activities below tasks. This is not difficult by any means. If you can provide a sandbox environment for users to explore, all the better.

The second component, Reflect, requires more tact. I don’t think I could incorporate reflective questions in a help topic without sounding corny (e.g., How did creating a new widget make you feel? What did you learn from your experience in adding a new administrator?)

However, if we alter the reflection element a bit, changing it to “Real Scenarios,” it sort of works.

Mark Baker recently wrote a post that’s relevant to this point about reflection. His post, The Real Docs Need Is Decision Support, talks about the need to go beyond technical instructions and instead provide users with decision-making information for real business scenarios. Mark writes,

My field is software development, after all, and not everything in the software development world is done through a GUI. For programs, scripts, and command lines, the mechanical details of command syntax have to be clearly documented. But even where documentation of mechanicals is required, it is never enough. The real tough parts of these tasks are the decisions, large and small, that have to be made along the way — decisions as large as whether and when to do the task at all, to as small as how to choose the right value of an individual field or parameter.

Perhaps the reflection component, so critical to learning, could be included as an exploration of how to apply the technical knowledge to real business scenarios? The basic outline of a help topic might look like this:

  • How-to Steps
  • Practice Activities
  • Real Scenarios

For example, instead of the corny questions I posed above, I might ask the following:

  • How can you use this widget during the sales cycle to reduce communication overhead?
  • How many administrators might you want to designate to help keep the data up-to-date?

I’m not sure that merely asking the questions provides the business decision support information that users might need, but it’s a step in the right direction. (Perhaps a real rather than fictitious scenario might be easier to model.)

Why Help Fails

Mark’s post emphasizing the need for business information hits on the findability theme I’ve explored on my blog at length. If users need business specific information, not just technical how-to instructions, then their searches for this information will fail if the help doesn’t include this information. Help will end up being a set of mostly obvious topics (except to tech novices) that fail to have any valuable information.

We talk a lot about different techniques for findability — including indexes, glossaries, organizing the content well, etc. But the largest factor in that equation is the content itself. If the content doesn’t address the real questions users have, it doesn’t help users. They won’t find their answers in the help because the answers aren’t in the help.

Why We Omit Business Information

Why exactly do we omit this kind of business information? Because it’s hard to write. I once worked on a sophisticated traveling/scheduling application that had an accompanying binder written by the department’s secretaries detailing very specific procedures and workflows that weren’t part of the application’s functionality. Information such as, send “John” a reminder e-mail once you put the report in his inbox,” or “The information must be included in the Y report and sent out on Monday; then wait a couple of weeks for it to process,” and “Betsy is the one who processes this information and you can call her at 2-5555 with any questions,” or “The yellow sheet at the back is the only important information in the report….”

That kind of stuff. I said I’d have to move in to their department and live among them for a few months if they wanted me to document their business process. (I never did.)

In a previous job, I wrote documentation for financial analysts. One time I remember documenting a short sale analysis application. Not having a Series 7 license myself, I found a lot of the concepts difficult to understand. I was grateful enough to correctly document how the application worked. But expanding the help to include advice on short sales and stock trading scenarios as it applied to the application’s tools would have been somewhat miraculous. Although it would have been great to include this information, doing so would have required a lot more knowledge than I had.

In short, we omit business information because this kind of information is hard to figure out. It’s often specialized to a specific group or industry, and it changes periodically. It’s not something you can figure out by merely playing with the application on your own, which is how I like to discover a lot of the help information. You have to milk business relevant information from a SME, if he or she decides to explain it to you.

Additionally, business information for one group may vary for another group. If your application is used by a variety of people, from companies in Europe to non-profits in Canada, no doubt the business processes for each group vary. How then can you write relevant business specific information if this information is so variable?

Moreover, if you did start to expand the help with business information, don’t you risk increasing the size of the help material to an undesirable length? The user who checks the help for information how to configure Widget X now encounters a 22 page chapter about all the uses of Widget X — but no instructions on how to actually configure it! (At least none that he or she can find.)

I still value and applaud the effort to include business decision-making information in help material; I just want to acknowledge the difficulty of doing so.

Why We Omit “Learning” Information

I started this post by talking about a model for learning, and then I veered a bit towards a discussion of whether to include business information, which some consider extraneous to the core material of help, while others feel it gives help a heartbeat.

Now let’s explore why we often omit learning information — the reflective questions, the practice activities, the extensive scenario-based tutorials, and so on.

Going down this road to learning opens up the age-old question about tech comm versus instructional design. Current trends in tech comm encourage writers to adopt a minimalist style. Include only the bare minimum of what the user needs. Stop glucking up your help with all kinds of conceptual explanations the user doesn’t want. Get rid of stem sentences as well. Just cut all the fluff and focus on quick, easy, task-based steps, because the user doesn’t want to spend time in your help material. The user wants to go in, get the information, and get out. You have about 10 seconds to let the user do that before his or her patience and frustration reach their threshold.

With this minimalist mentality, is it any wonder that we skip the learning objectives, practice activities, and reflection questions? All of these learning components assume the user has a lot of time and nothing better to do than to explore all the modules and exercises and scenarios and question-based activities in your help material. Sure all of this leads to “learning,” but the user is so eager to be done with help that learning gets shelved for more time-efficient action.

As an example, have you ever wondered why the instructions for the 1040 EZ tax form don’t include any activities for learning? There aren’t many practice activities or reflection questions, even though such material would help me learn to do my taxes better. No, those tax instructions are already 40+ pages in length. Who wants to extend them even more, converting them into a homework-like workbook? Only someone who is considering a tax emphasis in pre-law might think this is a good idea.

This leads to the question: what sort of users have time to learn? Few people look forward to going into a Learning Management System (LMS) to complete a course. I currently have a three-week-old invitation waiting for me to complete the yearly security awareness training, which will require me to sit through an LMS, proceeding screen by screen as I read quotes, answer questions, consider the right choice for fake scenarios, click response buttons, and get inspired by watching 30 second clips of leaders reading lines fed to them on a teleprompter.

Is it just the tech writer in me, or don’t most people prefer a raw go at the information, a chance to read it and spit it out in a quick completion test rather than having to “learn” the material?

A while ago I sat through 20+ minutes of excruciatingly long e-learning for a Boy Scout volunteer requirement. The e-learning was well done, with video scenarios, periodic quizzes, short things to read, and decisions to make. Throughout this 20+ minutes, I was probably learning a great deal more than I would have if I’d just read the same information. The e-learning techniques were no doubt searing into my brain the importance of “two-deep leadership” and how no leader should ever be alone with the boys.

Well, after I painstakingly “learned” all of this material, it turns out I couldn’t complete the quiz at the end because I had used a tablet device to view the video, so I had to replay the whole thing again in the morning on a desktop computer and “re-learn” the material once more. (By this time I was just gaming the system and using Alt-Tab to multi-task between video segments.)

I don’t mean to be so hard on learning. There are times when I’m in the mood to learn. One time I wanted to learn Visio and stumbled across an excellent tutorial from Microsoft (and raved about it in a post). Doing all the practice activities really did help me learn the application. The key difference, though, was that I was in a mindset to learn. I had set a goal to learn a new application, and with that goal, I found time to stop whatever I was doing, sit down, and carefully learn.

But unless the user wants to learn, including learning activities seems only to get in the way of the user’s main goal: to get information quickly.

Conclusion about Learning and Business Information

Although including business information and learning activities into help can be worthwhile, doing so poses a number of challenges. It can be difficult to gather the business information, especially if you’re not an expert in the field. The business information may change radically from group to group and quickly become outdated.

Including learning activities may help users who want to sit down and learn, but this mindset rarely describes the typical user of help, who is often frustrated, at her wits end, and eager to complete a time-sensitive task.

As a result, although expanding help with both business information and learning activities may be appropriate in some contexts, more often than not this extra material is something we don’t have time to write.

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.

12 thoughts on “Incorporating Learning into Tech Comm Deliverables

  1. Fer O'Neil

    Nice–you must be in a more playful writing mood after the Thanksgiving break. I especially liked

    “But expanding the help to include advice on short sales and stock trading scenarios as it applied to the application’s tools would have been somewhat miraculous”


    “Only someone who is considering a tax emphasis in pre-law might think this is a good idea.”

    I think there is something here that could really help the ID folks as well as you describe from your personal experience with e-learning. Perhaps ID should look at their designs from the two perspectives you mention: 1) to get information quickly and 2) wanting to learn. e-Learning could then be developed to address these two motives and maybe the user could even be given the choice of which learning module to complete. This could work both ways too–tech comm could focus on the “get info quickly” motive but offer additional real-world scenarios for learning concepts.

    1. Tom Johnson

      Fer, thanks for commenting. I think ID people would incorporate branching to accommodate the advanced users who want the quick version, right? And for those who want more detail, they can trudge through the extra activities.

  2. Kath McNiff

    Great post and very timely for my tech comm team. We write help, guides and video tutorials to support a software product for researchers (social scientists, enthnographers, phd students etc). These people approach their work from all sorts of angles so we can’t afford to be too prescriptive.

    But many users (especially students) are constantly asking for more ‘conceptual’ help (or ‘business information’) – sure, they need help with using the software but, more importantly, they want strategies and techniques for approaching their research.

    This is fine, but as you point out, we want to embrace minimalism and avoid “glucking up” our help – since most users would rather drink hemlock than spend any time in it. So what to do? Maybe the help is not the place for this sort of ‘learning’. Maybe the software should provide more direction. Sheesh.

    I do like your ideas about ‘reflecting’ – it’s exactly what your post forced me to do!

    1. Tom Johnson

      Kath, it’s good to hear that users are asking for more conceptual help. If you can include strategies and techniques that apply generally, I think that would be a good thing. In this post I just raised a few difficulties in doing so, but really it takes a higher level analysis and approach to write that kind of material. When you manage to do it well, the information has a lot more impact.

  3. Larry Kunz

    Does the reader want to learn? Does the reader need to learn? I’d say that the user of the 1040EZ tax form doesn’t need to learn, and almost certainly doesn’t want to. Similar, the person assembling an IKEA table doesn’t need or want to learn. They just want a table.

    Our audience analysis should always take into account whether the reader wants or needs to develop mastery of the subject. Many (most?) times the answer will be no. But when it’s yes (or maybe) we can use techniques like progressive disclosure to make learning content available to be used whenever it’s needed.

    Nice post!

    1. Tom Johnson

      Thanks Larry. Giving users options about how they want to learn seems like a good strategy. A few dropdown hotspots that offer things like Practice Activities or Further Exploration wouldn’t really get in the way too much.

  4. Gallagher

    I consider myself a technical writer, but I focus on writing exactly what you talked about – documentation of business decisions. Mostly I write job procedures, which include all the forms that must be filled out, and how to make decisions on entering them into a system, and then how to notify others via e-mail. For example, how to pay an invoice. When we receive an invoice, somebody needs to interpret and make decisions on how to enter the data related to the invoice into a system. If the vendor is new, there’s a whole set of decisions on how to create a record for them in the system. Then someone else needs to make decisions on whether to approve it, and how the expense should be allocated. And finally someone needs to make decisions on how to pay it (we have multiple bank accounts in multiple currencies). We use a lot of If/Then tables for these decisions, and sometimes the key field that determines a decision changes from step to step (e.g., early in the process, invoices are grouped as either corporate or project based; later they are grouped based on payment method, then later by bank account).

    So I have to encompass what’s both inside and outside of systems. It’s quite interesting to read that for software documentation these decisions are mostly out of scope. We do build many internal applications at my job, but there isn’t a software tech writer (would be nice, though, then I wouldn’t have to get into system details in a business procedure!).

    1. Tom Johnson

      Gallagher, what an interesting and important job, documenting business decisions. Your job actually sounds like a lot of fun. It sounds much more cerebral and interesting. I do think these business decisions are important to include in documentation, but how do you get around some of the difficulties I raised in this post? If you have disparate groups with different purposes, needs, etc., how do you provide recommendations that fit them all?

      Additionally, do you have to acquire a subject matter expertise level knowledge to enter the business decision support arena?

  5. Jonatan Lundin

    Tom, you say about minimalism: “Current trends in tech comm encourage writers to adopt a minimalist style. Include only the bare minimum of what the user needs.” and “With this minimalist mentality, is it any wonder that we skip the learning objectives, practice activities, and reflection questions?”

    This is a true misconception of minimalism. I’ve heard many, many technical communicators say that minimalism is about brevity; to just give the user the “naked” instruction and nothing else. To slash the verbiage, to reduce cost in making technical documentation etc.

    To me, this was not the intentions of minimalism. Minimalism is about learning. Incorporating learning as a way to make the user an independent learner is what minimalism in its essence is all about.

    A minimalist instruction is heavily learner oriented. Minimalism is based on the idea (based on theory by Jerome Brunner also on Piaget and Dewey) that users learn by exploring, by being active, by (sometimes) doing errors. To read-to-learn are not what people want; they want to be active and explore on their own.

    A couple of guided exploration cards make up a minimalist documentation. A guided exploration card can be seen as a (DITA) topic. The card does not have to be a step-by-step instruction. Most often it is an advantage to not use the step-by-step as the main body in an exploration card. The card (topic) invites the user to explore the product; it guides and supports the user in exploring the product to learn about it instead of guiding the user through detailed step-by-step instructions.

    Minimalist documentation shall also support error recognition and recovery since it is likely that the user will err as a consequence of discovering the product. Minimalist documentation shall support the user in reflecting and “try-on-your-own”. In many guided exploration cards you will find passages such as “Try using some of these buttons…”, “Now try to select a…”

    I’m not saying that I’m a big fan of minimalism. I’d just want to defend the minimalist design approach agenda as I see it being misunderstood so many times. A consequence of doing minimalism CAN be that documentation becomes “fewer pages”, but it can also be the opposite which depends on what you had before. The intention of minimalism was not “to reduce number of pages and reduce the cost of technical communication departments”. Doing minimalism well most often do not mean a cut in cost; most often the opposite.

    I argue that users do in many cases not care about learning, since our modern hectic world does not allow us to spend time on learning. In the professional knowledge worker landscape of today, users have probably much less time to explore and learn than they had when the minimalist design approach was called for some 30 years ago. There are many situations where a user just wants to get the product to work. And, the amount of information to search is increasing and the time users have to spend on searching is in many cases decreasing which means that our focus as technical communicators has shifted to findability instead of “learnability”.

    My position is that many users of today do not invest time in exploring the product. They want the answer to a question, and they want to find it fast. The answer can be a detailed step-by-step instruction needed to solve a problematic situation. As technical communicators, we must predict user questions, write the answers and make them findable. Many answers are decision making support.

    1. Tom Johnson

      Jonatan, you’re totally right. I think I misrepresented minimalism in my reference. I mostly meant concision and brevity, and by referring to this as minimalist, I inadvertently brought in all the connotations of minimalism as a practice. Thanks for adding this detailed explanation to clarify the concept. I didn’t fully realize that minimalism involves a theory of learning behind it. In that sense, then, you have somewhat deconstructed my post! :)


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=""> <strike> <strong>