Do We Need a New Approach to Help? Why Are Users So Apathetic Towards Help after 50 Years of Innovation?

I’ve spent the last few days at UA Europe in Manchester, England, where I was invited to speak. I’ll shortly post recordings of my presentations — one on findability, and one on video tutorials. Both are important topics. But there’s an even more important topic I haven’t addressed much: the content of help itself.

Conferences usually prompt reflection of some kind, especially international conferences, where attendees are much more diverse (24 countries present), and UA Europe was no exception. On my last day in Manchester, I started writing this post from the historic John Rylands library, surrounded by old books in glasses cases, set in a cathedral-like building.

John Rylands Library

(In the spirit of my environment, I thought about writing this post in Latin, since most of the books in the library were in Latin. But Latin is a dead language, and alas, I do not know Latin.)

False assumptions

I used to think that if I could just help a user find the right topic, one that addressed his or her question, it would help users learn what they needed. I assumed finding the right help topic was the difficult part. Getting the user to that exact topic that answers his or her question at the right time, in the right moment, and so on, was the ultimate problem to solve in tech comm.

Hence I started this series on findability. Eighty posts later, I still think findability is a key issue (one that I’ll continue to write about), but there is an even greater issue to address: the content itself.

Even if you get a user to the right topic, the topic often fails the user. Many users know this, which is why they often don’t bother to consult the help at all.

One problem lies in the form of the topic. Do users learn from a linear sequence of task-based steps? Do topics that say, “To do this, follow 1, 2, 3,” help the user learn how to use an application? For some tasks, sure. But for many others, no.

In John Carroll’s writings on minimalism, he argues against systematic instruction in favor of experiential and more self-directed learning models. Mark Baker, an experienced structured authoring guru at, explains,

We are so ingrained with the idea that systematic instruction is the correct way to teach, that if you just read about, or are taught, minimalism as a method, I think you are almost certain to fit its precepts into your underlying idea of systematic instruction. We need to be hit over the head over and over again with the evidence that it does not work, and that is what Carroll does, in highly readable and engaging prose, chapter after chapter.

And Laura Palmer, a professor at Southern Polytechnic, adds,

Carroll wanted to leverage experiential learning by providing users just enough content to get started, etc. As Mark says of Carroll’s findings, people don’t follow procedures so traditional, linear step-by-step processes made no sense. Factor in pre-existing mental models of how users approach a task (problem) and leading the reader is pretty much an impossibility.

See What Exactly Is Minimalism?

However you interpret minimalism, at the core of the discussion are questions about the efficacy of traditional help. I don’t think the tech comm community has really addressed how to fix the help problem in a way that transforms help from a tossed-aside, undervalued artifact to a sought-after, friendly guide that users love. Help still more or less remains as disdainful as before, despite all the advancements in content re-use, technology, and methodologies. Why does help still kind of suck even after so many years?


Tasks often don’t address real scenarios

A couple of UA Europe presenters touched on the limitations of the task-based topic. Leah Guren presented on moving from tasks to workflows. She noted that real scenarios often combine multiple tasks in various contexts.

For example, although your phone’s guide might explain how to access your contacts and how to make a phone call, you rarely see information on how to access your contacts while making a call.

Here’s another example. In Illustrator, you can learn how to use the pen tool, the reflector tool, the shape tool, the line tool, and the color gradient, but do you know how to use them all together in context of each other?

How do you draw a particular object (such as a beaker with liquid in it) that requires many different tools, used in combination with each other? How do you use the tools like an artist who dips his or her brush into multiple colors, mixing them, applying different textures and strokes at different weights, creating not just basic shapes but a masterpiece?


Help starts with features rather than the user

Leah mentioned another key point. She said tech writers often start by documenting various features of an application rather than by starting with the user and his or her goals.

Although her principle follows a classic user-centered documentation approach, I’m guilty as the next tech writer in ignoring it. I typically start by figuring out what a tool can do, and then I describe how to do it. One assumes the tool was built to solve user problems, but that’s not always the case. Leah says if you start with the user first instead of the interface, there’s a world of difference in the result.

Instruction separated from the interface is meaningless

Another presenter, Ray Gallon, noted that separating instruction from the interface decontextualizes the information in a way that removes its meaning. The help text means little without the accompanying interface or product.

That’s why so many users don’t start out by reading the manual before diving into the product: you can’t understand the manual without the interface. Hence the trial and error method first, and then the manual (if needed) later. The reverse order doesn’t work. Cognitive science backs this up, Ray says.

Ray advocates putting help in the context of the application, specifically delivering help inside the application in a context-senstive way. Here’s a slide from Ray’s presentation:


I think context-sensitive help is a great practice, but of course it’s not the end-all solution. With context-sensitive help, users get the tree view instead of the forest view, and space is so limited it’s hard to give the kind of detail warranted. Still, there’s a workaround: bring the user interface inside the help, which we often do through screenshots and other illustrations.

General opinions of help are still poor

A while ago, I wrote a post called From DITA to VITA, which was my way of tracing the evolution of help and proposing the next step. In the early days of tech comm, some writers used a method called STOP. It was a two-page spread with an illustration and text. You could pin up the two pages on walls for people to look at.

The STOP method

The STOP method has a graphic on the right and text on the left. Content cannot exceed these two facing pages, and you must always have a graphic, even if you’re only visually depicting your argument.

Help has undergone many transformations since then, and no doubt many of the advancements toward content re-use and multi-channel publishing have been significant enhancements. Don’t get me wrong — we have come a long way, and many of the steps have been positive improvements for the availability and impact of help, particularly in many languages and formats.

But why is the user’s experience and reaction to help generally still the same? Why do so many people still feel documentation is useless? Does help follow a model that fundamentally doesn’t work?

No matter how efficient you are in re-using the same topic in multiple formats, if the topic doesn’t connect with users in a way that helps them learn, what good is that efficiency? What good is findability?

I could be wrong about my assumptions here. I wasn’t around 50 years ago to sample users with help material. Regardless, it seems like the general attitude of users toward help remains somewhat the same.

Before any other improvements, we have to make help information worthwhile to find. It doesn’t make any sense spinning our wheels trying to improve findability when we’re just building roads to barren lands.

We need a better approach

Ray Gallon explored many angles on learning in his presentation about cognitive science. Experience and exploration play huge roles in learning. Ray has a series of recordings on cognitive science.

Ray talked about various levels of learning, beginning with routine tasks and moving to the top: innovation and community building.

I think Ray brings a lot of insight into the help situation, and the principles aren’t easy to implement. That’s why a lot of technical writers consider themselves information developers only; they leave the “learning” to the instructional design folks.

But a consequence of this apathy about making material learnable/enjoyable/interesting is that few users see the value of help. If there’s one recurring discussion among tech comm circles, it’s that few people seem to value the work we do.


The corporate value theme recurs so frequently, one has to start to believe there’s some truth to it.

Plain text is just one mode

Sticking with plain text taps into just one type of learning our brain can process. Imagine a web where everything is plain text. No images, no video, no sound, no animation, no interactivity — just like living in Notepad all day. What a dull place.

If we want to engage users in the same way users get engaged by other web content, we have to make our content more web-like. We might include the following:

  • Video tutorials
  • Illustrations
  • Concept diagrams
  • Exercises
  • Storyboards
  • Scenarios
  • Simulations
  • Interactivity

No one has the bandwidth to do that for every help topic, and obviously some topics would be better candidates for some visuals more than others. But to move beyond text, I think we have to move towards non-text forms, drawing upon as many forms as possible (but mostly visual forms).

In fact, there’s a whole learning theory about dual encoding that tech writers would benefit from implementing. Why do you think TV is so popular? a friend of mine (an instructional designer) asked. Because of the dual encoding with audio and visual — the brain just absorbs it.

Our brains encode more than language

Think about the many different parts of your brain. How many different modes does a plain text approach reach?


We have a lot of dimensions that allow us to process information and learn. Even if we just added more illustrations, video, and some scenario-based activities for the user to follow, it would probably make help turn the corner from boring to alluring.

We love language too much

One problem is that tech writers tend to be language lovers only. Academics pitch our discipline as one of the many options for English majors and others who love language.

In fact, the closing keynote at the UA Europe conference was by David Crystal, a prolific linguist with 120 books to his name, including the bestselling The Singular History of Spelling in the English Language. His closing keynote was engaging, thought-provoking, and mesmerizing in many ways. It’s probably the best keynote I’ve seen (even better than David Pogue).


The fact that I liked Crystal so much also troubles me. It troubles me to be so interested in language at the expense of other modes of learning. Language and text are clearly my preference.

And so it follows that I write a lot of text. Text is fine — this blog post is 90% text. But I think we need to think of ourselves as multimedia artists, illustrators, video producers, instructional designers, business analysts, and digital storytellers. If we did, users would be a lot more engaged by what we create.

Our natural inclination for text may satisfy our preferences, but not everyone loves language so much. Our blindness towards audience awareness is ironic, given that rhetoric (the practice of targeting the message to the audience) is the foundation of writing.

Text is the easy route

Another reason why we fall back on a text-heavy approach is because text is so easy. Try explaining a difficult concept through the visual medium. It’s much more difficult. Part of the beauty of text is that it allows us to communicate extremely technical information that’s just not possible to communicate any other way.

But in those attempts to explain technical concepts, we often forget that the meaning of words is slippery, because language is imprecise. Understanding depends on assumptions that aren’t always shared. Perspectives are informed by biases and culture and experiences that vary. What’s clear to the writer may be incomprehensibly muddy to the user.

But through visuals, you put an extra reinforcement to the meaning of your words. Where language fails, visuals communicate. Visuals simplify and distill meaning, forcing writers to communicate another way, to another part of the brain.

Notice how text begins to slip away into meaninglessness in the following image, but is then saved by a visual that clarifies everything.


Those reinforcing visuals can be the application interface itself, if you’re contextualizing the help information directly in your app. Or if you’re writing outside the app, you can bring the app to your content, or create conceptual diagrams illustrating your ideas.


As we engage in an approach that goes beyond text, focusing on ways to enhance our communication, the result will be much more engaging, interesting, and learnable for users.

One day I hope that, after introducing myself as a “technical writer” to someone, the person will greet me with an enthusiastic cheer and a quick smile, instead of the typical apathy and sarcasm that I usually receive.

What do you think? Do you see a need to make help better connect with users? If so, how would you do it? What forms besides text do you think would be useful to include in help material?

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.

  • Ellis Pratt

    A lot of technical documentation is driven by regulatory/legal needs, plus the complexity of localisation. These have an impact on the content that’s provided (to avoid getting sued) and how it’s created.

    Innovation is happening, but it’s often from people outside of the profession – people who don’t seem themselves as technical writers and haven’t been taught the “right” way to do things. In most cases, they are not tied down by the limitations of localisation – they are only writing in English.

    I was only up for the Adobe Day, and I was struck by the assumption that technical writers will create video in the future. I don’t see this as a given – there’s a good chance a new profession will emerge that will do this work.

    • Tom Johnson

      Ellis, sorry that I missed you in England. I never seem to factor in Adobe Day when scheduling flights.

      It’s interesting to hear your perspective that perhaps another type of people, outsiders to tech comm, will fill the gap here, especially outsiders to the profession. I think this is why the Write the Docs conference in Portland was so interesting.


  • Ray Gallon

    Tom, a thoughtful piece, and dead on, in my view. Cognitive scientists, and John Carroll is included, stress that learning by doing is one of the best ways to anchor learning in memory. One reason for that is that several of those neuronal paths that you illustrate are stimulated at the same time (visual, textual interpretation, motor, etc.).

    For that reason, use of multiple information paths (visual, audio, text…) is encouraged, to reinforce the message.

    Those of us who do power point presentations often sometimes also forget that the reason you put a few bullet points, or an image, up on the screen while you are speaking is that same function of anchoring parallel presentations of ideas in memory.

    By the way, the diagram of the various Adobe Illustrator tools used to create the beaker image seems to me to be a perfect paradigm for a help starting point in a tool-based interface such as Illustrator or Photoshop: You put a simple example of a kind of image to be produced, and surround it with the tools used, as in your illustration.

    Clicking the image itself produces a video showing the process as a continuity (workflow).

    Hovering over each tool produces a popup choice of resources (video, text, etc.) that the user/learner can select according to need and learning style, related to that tool. The content is specific to the task of creating that image, and doesn’t deal with other possibilities of the tool. If the learner needs to find those out, they should be no more than one additional click away through related links.

    Seems like a winner, to me. What do you think?

    • Tom Johnson

      Ray, thanks for commenting. I really liked the ideas you explored in your presentation. I agree about the approach you described, with video callouts linked from text descriptions.

      I’m wondering if you have any thoughts on how to take the rights steps in the direction of experiential learning. Many topics in tech comm don’t merit an experiential component. But usually a tutorial of some kind at a higher level, referencing a lot of different topics, fits in well. Where do you draw the line between instructional design and tech comm? It seems like ID involves a lot more experiential-type activities, but with tech comm, a lot of our output is raw information rather than learning.

  • Fer

    Useful post, Tom, thank you for elucidating on a topic that I’m sure many of us are very interested in. With my tech docs, we are looking at making some drastic changes along the lines of the more “web-like” and engaging content you example. I look forward to more posts on this topic as I work on implementing these changes; putting your theory to practice and seeing where I end up on the other side…

    Re: Ellis, I agree and disagree in part. I think there are many technical writers who are willing and able to “reinvent” themselves if just given the chance. And whereas I can see the benefits of creating entirely new positions for some of these aspects of the ‘new’ technical communicator, there are also many advantages for keeping it within the existing field. I, for one, think that those who self-identify themselves as proverbial “technical communicators” are the best people to create the kind of content (any content, using any medium) for users; now and in the future. It takes more than a new skill and practical ability to “create video” for technical documentation purposes–there is audience analysis, rhetorical understanding of language and tone, cultural awareness, and so forth.

    • Ellis Pratt

      I agree many technical writers are willing to change. The resistance often comes from outside – “that’s training’s role”. There’s the added difficulty of lacking the skills (like adding embedded Help into a C++ program), and the challenges of convincing senior management. Technical Communicators are generally skilled in writing, so that’s often what they fall back into doing.

    • Tom Johnson

      Fer, thanks for commenting. I don’t have any quick answers. It’s always easier to raise problems rather provide solutions. I do have some thoughts but nothing that you wouldn’t know already. I’m curious to know how you’re revamping your approach to help. What are you doing differently, and why do you think it will be successful?

  • Ray Gallon

    Ellis, I agree that technical writers won’t necessarily produce videos. I also think that technical writer, today, is a dead-end profession (or at least job title). I don’t mean to suggest that we won’t write in the future, simply that that will not be enough to keep us working. A good technical communicator needs to also understand some aspects of one or more of the following:

    User experience design
    Business analysis
    Information architecture
    Content strategy
    Globalisation (necessary before you can do effective localisation)

    • Ellis Pratt

      I wouldn’t be quite so gloomy. There’s an awful lot of safety, regulatory and legally required content.

      I also see a marketing copywriting skills in the mix. Technical enabling content is becoming more important in the marketing funnel (see Google’s Zero Moment of Truth), and technical writers can adapt to suit that requirement.

    • Chris Despopoulos

      Personally, I don’t see any gloom in this prospect. I presented my A-Ha! moment at Adobe Day in Manchester, and it’s this… Any product you want to thing about (car, bridge, crop of wheat, or even software) is largely an exercise in information management. Those who call themselves Technical Writers are information professionals. There’s a vast spectrum of information activity involved in a product, and that translates into many entry points where we can add value.

      Adding value is the key. I don’t care what your job title is, if you don’t add value you won’t be working. The information we deliver is spreading out to other media. One medium is the interface for the product itself (car dashboard, bridge testing and monitoring procedures, crop sales cycle, software user interface). We have lots to add there, since we work as user advocates, concentrating on the user’s experience. Another medium is in project planning, where developing user roles and use cases is important. There’s no shortage of work to be done, it’s just that the traditional focus is blurring.

      Yes, we have to consider other media. But I think that means a heck of a lot more than doing videos.

  • Shane Taylor

    Great post as usual. I agree completely with the reminder to refocus on user goals and workflows rather than features. Minimalism? I would like to see help that uses both a minimalist and step-by-step approach, showing the steps only on request (progressive disclosure). Ideally, the help system would collect data on a) topic views and b) clicks to view the steps for each topic, so you could learn how useful this approach is (or isn’t) and which topics require steps.

    • Tom Johnson

      Shane, thanks for commenting. I agree that progressive disclosure is a useful technique that has a lot of potential here. Progressive disclosure is one reason I like drop-down hotspots, but the hotspot technique has other usability problems.

      Re minimalism, I would like to come up with a new term that more accurately reflects a new direction. Too often, minimalism gets reduced to cutting text.

  • Vinish Garg

    As we continue to talk how the help deliverables have evolved and how the users expectations have raised the benchmark every time, let us not forget that users referred to the tri-pane help 20 years ago to understand a procedure, and a segment of users still refer to the knowledgebase when required.

    The help-still-sucks notion keeps ringing primarily because
    (A) increasing users’ expectations map directly with evolving technology. As the web design and UX trends continue to change with time, it directly impacts users expectations in documentation as well and it is fair enough
    (B) this is also about the changing temperament of users (isn’t it?) When users refer to YouTube to see how to bake a cake, to fix a broken lamp, or to install a music player in the car, they may not have the temperament to read a page long procedure anymore.

    Here, we see a direct correlation between A and B, and this is where technology-use gets even more important in planning the documentation deliverables.

    For all changes in web design and UX trends, the single most important objective has always been to ‘engage the user’. This should be the first step in planning the documentation as well–to ‘engage the user’. And to engage, you nailed it rightly when you say the documentation should include videos, storyboarding, concept diagrams, besides written procedures. And a technical communicator can do it effectively when (as Ray said in his comment above), one has a reasonable mix of UX, IA, BA, and CS skills.

    Now the challenge is to plan for such deliverables for UX and to keep the users engaged. And this is the reason why I prefer a CMS over a HAT, any day.

    • Tom Johnson

      Vinish, good points. I agree that engaging the user is key. The company I work for is all about solving the “engagement crisis” through gamification. So naturally I think gamification could be one of those tools that encourages action and as a result, engagement. But definitely the other visual mediums you listed also help produce engagement. This is a great discussion that I hope continues in the right direction.

  • Derek Warren

    As expected, great points and questions, Tom. And having read all of the responses, I again realized how open discussions reveal something great: common themes where the ‘heart of the matter’ is exposed.

    I’ve always been a bit of a rebel when it comes to pushing the envelope. In fact, I’ve ticked off some of my managers at various companies. My ambition began (or was at least fueled) during a company all-hands meeting when a customer support rep stood up in front of the entire, global company, and proclaimed that the company’s “doc sucks!”

    In all fairness to those managers whom I have “offended” and to that customer support geek’s insult, they represent two counterpoints to this topic: first is the prohibitive costs of funding tech writers to go wild with multimedia. It simply costs loads of money, depending on what it is you hope to do. But even low-fidelity multimedia efforts can add up quickly. Ambition is often blind to those ugly realities, like we tend to be toward death and taxes. And since most doc teams are understaffed these days–reality: we are perceived generally as a necessary liability rather than an asset; how much money does your doc team MAKE for your company?–it’s a tough sale to procure even 50K for the tools, training, and personnel.

    As to the second point made by the CS geek, he was right in the same way you are right: if doc doesn’t actually help make a customer successful, then it does suck! (Arguably!)

    So if we could be either perceived as a significant part of the money-making machine in our given organizations (e.g. 20% of revenue is clearly traced to the doc team), or if our doc “products” really did represent a significant source of revenue, we would likely gain some popularity, at least among the bean counters and executives who actually spend as much of their time on profitability concerns as we do on text vs. images vs. videos vs. workflow vs. task-based doc, etc.

    So for me, I think the key takeaway you’ve inspired in me is this: when we find ways to accurately trace our impact on a companies bottom line and then innovate around ways to increase company profitability through whatever it is that we do (since at our tech comm conferences, we rarely if ever discuss this), we are heading in the right direction. I think a good article (or book) could be written on the subject of tech comm value, both perceived and real. If we are after “being valued,” as I think your overall article conveys, then asking the question, “How does what I do help to make my customer, and therefore, my company, more successful (aka profitable)?” can help us talk directly to measurable improvements.

    Thanks for waking my brain today!

    • Tom Johnson

      Derek, it’s great to hear from you. I know that video is more expensive. There also seems to be more of a defined window for video as well. You can’t create video until you have a working application. And it’s often months before that happens.

      Anyway, I guess the challenge is to create video cheaply enough that it doesn’t cost thousands of dollars. The trick is persuading the company that youtube-like videos (amateurish, I mean) are acceptable in a corporate context.

      You’ve inspired me to look at ways to incorporate video in a less expensive way that doesn’t get trapped in small release windows.

      I hope everything is going well for you. Are you still at Venafi?

  • Greg DeVore

    Great post and the answer is most definitely a resounding “yes!”

    We have been working on this problem for several years and have had great results with our own docs and those of our customers. You bring up so many points that is hard to address them all in a comment. Here are some key ones:

    Documenting tasks: You are exactly right in saying that task based documentation can be rendered useless if you document the wrong tasks. Task-based documentation that doesn’t really understand what a user wants to do isn’t much better than feature descriptions.

    They key is to answer real questions that real users have. We encourage our clients to grab support tickets, write down the actual questions users are submitting and write help articles that answer those specific questions. You end up writing many more help articles but the articles you write get used a lot. And your support team will love them.

    Using images or video: Images are so important. It is such an easy way to add so much context to what you are writing. But technical writers usually just look at screenshots and images as an added headache so they use them as little as possible. Or they are considered to costly to produce. In this day and age that just means you are using the wrong tools.

    Our customers use a ton of screenshots in their documentation and they regularly get rave reviews because of their documentation.

    Solving the help problem

    To really solve the help problem you need to fix the system for creating, delivering and updating help as well as the role of a technical writer in an organization.

    Process – Help needs to be created, delivered and updated in much less time. Delivery time needs to decrease from weeks or months to minutes or hours. Technical writers need to be able to update and respond to user feedback and questions. They need to be integrated into the support process so that they work in tandem with support staff and not as a separate entity.

    Role – Technical writers need to move away from deliverables and be tasked with helping end-users. The job isn’t finished until the docs are useful to the people that need to use them. That obviously wouldn’t work with the way that many organizations create their docs, but it is required if you are really going to make a difference.

    Help hasn’t gotten better in 50 years because most of what is written today isn’t that different from what was done 50 years ago. Realistically, many technical writers could still do what they do today on a typewriter. It might take longer and it might not look as nice, but the actual content delivered would be roughly the same. How can we expect help to be better if we could recreate it on a typewriter?

    @Derek is definitely on the right track. You can’t just complain that people don’t read the docs. You need to find a way to make an impact with the docs you are creating and then measure that impact. If you can prove you are making a difference you will get the resources you need.

    • Tom Johnson

      Greg, I really like your point here: “Technical writers need to be able to update and respond to user feedback and questions. They need to be integrated into the support process so that they work in tandem with support staff and not as a separate entity.”

      Some of the most useful help I’ve written has been when I played a semi-support role with an application. I think I’ll move more in this direction (integrating with support).

      Re screenshots in documentation, there’s a pervasive assumption in tech comm that users don’t need screenshots because they’re looking at the screen. I don’t agree with that logic. I align more with you — screenshots, especially when they have explanatory callouts, are quite powerful.

      Thanks for commenting.

  • Dee Elling

    Thanks for bringing these ideas all together, great post Tom!

    At our startup AppDynamics we frequently write topics in response to user questions, using a wiki for real-time publishing. While some “facts” about the software can be known ahead of time, many use case scenarios come to us after the product is in the user’s hands. The newer more intuitive UIs make product-focused help less relevant. The line between the content in help and in 3rd party press books is blurring. Your Illustrator example is relevant to this trend.

    Some of these ideas are also expressed in the principles used by the Head First series pioneered by Kathy Sierra and Bert Bates (


    • Tom Johnson

      Dee, thanks for commenting. I agree with your perspective about the need to write documentation post release, as questions come in through users and support channels. Especially in agile environments, a model of continuous publishing just fits.

  • Laura A. Palmer

    This is such a fascinating conversation…there’s way more here than I could comment on right now. However, I see some of the usual tensions about the profession in terms of do we stay the same (focus on writing), augment what we do (add capabilities), or let another profession fill in the gaps. All good thoughts especially with respect to help.

    I’ve always been interested in the problems with help. My early research focused on the shortcomings of Carroll’s minimalism with respect to the inclusion and, more importantly, development of a minimalist visual to accompany the text. Over time, I’ve been re-thinking these ideas within the framework of multimodal composition practices. As well, I’ve been considering if our understandings of audience are sufficient. The ideas coming out of information science with respect to information literacy (See metaliteracy: are thought provoking for how an audience/reader may or may not be able to understand what we produce.

    Anyway, my insightful colleague Keith Hopper had pondered the intersections between Tech Comm and Instructional Design for several years. He proposed they belonged together and would fill the gap so many of us see ( So, in addition to the program I oversee (IDC), we’ve now got another offering called Information and Instructional Design (IID). Could this be the intersection of professions where help is finally resolved?

    • Tom Johnson

      Laura, thanks for commenting and especially for sharing the links. I see that SPSU’s program bridges the gap between TC and ID in innovative ways. I think that’s a great philosophy.

      It seems there is a lot to talk about with both disciplines. It does seem odd that they are often so siloed from each other, both in corporate settings and in academics.

      You said, “Over time, I’ve been re-thinking these ideas within the framework of multimodal composition practices.” Just curious, but do you have a personal philosophy developed about how tech comm should operate? I’d love to see more detail about your insights.

  • Mark Baker

    Many possible things to talk about here. I’ve talked about some of them here:

    But I think it is also worth mentioning a what seems to me an oft-overlooked point in regard to visual communication. Communicating visually is extremely important, but it would be wrong to confuse communicating visually with communicating in pictures. You can communicate visually in text as well as in pictures. We can, and should, use strong visual and physical metaphors and analogies in explaining abstract concepts. A concept without a metaphor is like a boat without a sail — it leaves the reader all at sea.

    This is a practice you will find used widely in most fields of written communication, but it is singularly lacking from most technical communication. Graphics and video will doubtless play an increasing role in tech comm going forward, but prose will always be part of the mix. Let’s try to make the prose we write more effective by making it more visual.

    • Tom Johnson

      Mark, excellent point about communicating visually via text with analogies and metaphors. I agree that those kinds of visuals are often overlooked but are an important component of visual information.

      Thanks for adding a link to your post. You have a lot of insightful thoughts. I’ll respond in a comment on your post.

      Sorry for my delay. Having come back from the conference, I had a lot of catch-up to do at work, and then readjustment back into my regular life.

  • Chris Despopoulos

    All good points, but I want to stand up and cheer for text. There’s one thing text is really good at, and that capability is arguably responsible for the increasing velocity of technical innovation humans have enjoyed for a long time… Text is easy to combine, and those combinations produce unique ideas. Text is an extension of language, and linguistic combination is argued by some to be fundamental to the production of ideas.

    We’re on the threshold of combining text at a fine-grained level. I mean it, and I’m talking about combining help texts in response to user/product state. It may be a limitation on my part, but I don’t see the same capabilities for video streams or even graphics. But I really don’t think the time is far off when we’ll be able to ASK a documentation set things like:
    * Why should I do X?
    * When should I do Y?
    * How do I do A, B, and C if Z is true?

    And the documentation set will be able to lexically/semantically pull out the texts that pertain to the question and assemble them in a reasonable answer. (Probably the biggest problem will be getting a meaningful “I don’t know” from the system, but how many people do we know with the same problem?)

    Yes, video and other time-based streams will grow in use. (I was just asked by my employer to look into that, BTW.) And texts are getting pushed directly into the product interface… Maybe videos will start showing up there, too. But I’m not counting text out of the picture, not by a long shot.

    • Tom Johnson

      Chris, thanks for commenting. I agree that I probably overstated the need for visual elements in this post. Text is incredibly important and probably the content that most users need.

      Also, although I said the experience of using help remains in disdain (from a users point of view) even after 50 years of innovation, I am actually rethinking that. Users search for all kinds of questions on Google now and find answers. If you think of Google as a giant help file, user experience of help has skyrocketed. Anything you want to know you can find on the Internet in a matter of seconds. This is a tremendous leap forward. The problem is that users don’t see Google as a help file.

      Another point: Visual mediums are less important in more technical contexts. For example, developers like a lot of code snippets, much more than video tutorials (I think). Where visuals come into play is more with beginning users. Advanced users are often looking for specific answers, which text delivers well.

      I’m still mulling over part II to this post, in which I will try to take a step toward what I think would help make help more engaging/interesting/pleasing to users. Originally I thought that visual content would play into that engagement, but now I’m not so sure.

      What I think is that perhaps tech comm needs to drive information production based on support center cases. In many companies, tech comm and support are siloed from each other. Both groups would benefit from more tightly coupled integration. If tech comm can provide the answers that support needs, then we’re providing the right information users want.

      I do think that adding screenshots with descriptive callouts is a good practice (one that has been unfairly dismissed by assumptions about users not needing screenshots because they’re looking at the screen). And videos are also useful in many contexts. But screenshots and videos alone won’t satisfy the user’s need for information.

      The tricky part is figuring out how to write documentation that keeps pace with a support center. For example, if your support center gets 50 new tickets a day, and 10 of those might be answered via help material, how do you plug those gaps in your help? Do you write like a madman, adding content here and there as fast as you can and hope that the articles turn up in user searches (essentially replicating Google)? Do you document all the edge cases and unusual situations ad infinitum? How far do you go with providing information?

      I guess that the revolution of “Google help” is to provide information for the long tail. By this I mean we can see information about nearly every question we have, whether it’s a common or uncommon question. Most likely some information exists on the topic. The failure of traditional help in software webhelp files is perhaps a failure of scope — the answers the user is looking for simply don’t exist, so the user gets frustrated. (On the other hand, the answers usually exist on Google, which pleases the user.)

      So here’s a question for the people interested in this thread: How do you expand the scope of documentation so that users almost always find answers to their questions?

      • Greg DeVore

        Predicting every question that a user will have is impossible. And if you try to do the impossible you will inevitably fail.

        A lot of organizations run into trouble because their help writing process requires that they anticipate all questions. Their tools an processes don’t allow them to respond to questions quickly with documentation.

        We know we can’t anticipate every question a user asks so we embrace that fact and build our process around that.

        When a question comes in from a user and that question isn’t answered in our docs we create a new help article, publish it and send it to the customer. They get a great answer and our knowledge base grows with an answer to a real question.

        We don’t spend a lot of time trying to guess what users might ask, but instead respond to the things they do ask by growing our documentation.

        We use tools that make it possible for us to write a help article in 5-10 minutes and publish it right away. If the article may need more polish before we make it public we can publish it a draft like mode where only the customer we are responding to can see it. We can then clean it up for general use before we add it to our main knowledge base.

        I was at a presentation several years ago given by a military commander. He said that they had learned that while planning and research were important, success was more dictated by how quickly you could react to changes than how well you could plan.

  • Pingback: What have been your most successful experiences in connecting help material with users? | I'd Rather Be Writing()

  • Pingback: Finding a Starting Point: Answering Questions or Addressing Purpose? | I'd Rather Be Writing()

  • Jonathan Verney

    As a professional copywriter and scriptwriter, I come at this from a slightly different angle. My biggest issue with the help button is that it doesn’t match the way i learn the quickest and most effectively – by scenarios. I call it scenario learning because the topics are less important than the process, at least to me. Here’s an example. I recently purchased Paint Pro 5 from Corel. My impatience with the program comes from not understanding how to use it properly and not wanting to spend hours doing so. The help button is organized by topic, not by process or scenario. Not helpful. For me the best way would be this:
    Lie many, I have paid for an inexpensive photo I plan to use for my blog but I don’t want it to look like a visual cliche, in other words like everyone else’s photo. So I would prefer to learn how to do that. In other words, be offered say, a simple six step scenario approach to playing around with a photo (experimenting) until the photo is uniquely different and better suits the needs and tone of my blog. Instead, there are no scenarios and I’m left to decipher everything on my own.
    Not everyone learns the way I learn, but many do. I used to work for a company called Hypergraphics and that’s what we did. Scenario learning in print format (before the Internet:)). Sort of a simple graphics/ people oriented flowchart approach if you will. We had graphic designers and illustrators to take our flowcharts and turn them into fun illsutrations (You showed something like that somewhere in your article if I’m not mistaken.)
    Hope I haven’t totally confused matters, but then again this topic is worthy of a book (I should know, I’ve written several).

  • Pingback: Turning Around the Disdain for Help by Focusing on Content | I'd Rather Be Writing()

  • Saul Carliner

    Nice post.

    A few followup points:

    (1) One of the reasons that Help fails to ignite enthusiasm among our users is that we often show that we fail to adopt our own best practices.

    We’ve known for over 30 years that task-based writing is more useful to users than feature and function-based writing. We teach it in academic and professional programs. (The special issue of Technical Communication that featured task-oriented writing was first published 22 years ago this September.)

    But the sad and frustrating part is: (a) the approach continues to happen and (b) tech comm leaders allow it to happen. Leaders (managers who review work, instructors who review student work) can play a big role in fixing this persistent bad-practice but don’t.

    It would be easy to dismiss our responsibility by saying that SMEs demand it of us. And admittedly they do. But many software engineering and computer science programs are teaching SMEs how to create useful, task-oriented documentation.

    Our managers can refuse to accept functional writing when the material is intended for end users (functional writing has a place, but it’s limited in material intended for end-users), but they have to be willing to ask their staffs to rewrite content. Similarly, iyr instructors can require that students rework end-user material when it should be task-oriented but is produced as function-and-feature material.

    (For an interesting discussion of the engineering side of the task-oriented versus feature-oriented approach in the design of tablet computers, see Disruptions: Microsoft’s Struggle to Make Things Simple for Consumers by NICK BILTON at

    (2) The skills of visual and verbal (text) communication are different, and those of us who are writers are, unfortunately, doomed to primarily rely on words; learning to focus on images is a learned-act–often through great difficulty.

    One major university tried to offer a joint visual-verbal design program. The idea was that writers would become bi-lingual (so to speak) with a visual vocabulary and graphic designers would become bi-lingual (so to speak) with words. After several years, the faculty concluded that writers are writers and graphic designers are graphic designers; the best they could do was to make each party more aware of the value of the “language” they lacked.

    (3) As far as the use of videos goes, it’s not just a financial issue. The rise of low-cost video creation and editing tools has addressed much of this.

    But they pose a usability issue that few people raise: people listen several times faster than narrators can speak, so videos often take longer to review than text (which, for many users, is more efficient).

    Videos have their place, but the first question that technical communicators need to ask before producing them is whether the additional time needed to view the video is offset by the additional value to the user for watching it. For example, if the video merely presents instructions that a user can read and successfully perform without visual cues, then the video is probably of little or no use to the user. In contrast, if the video shows something that text alone or text and a single screen capture cannot show, then the video adds value.

    (4) As far as learning theory goes, it’s a great concept.

    But learning is defined by many in the field of education as a change in behavior (some branches use other definitions–but a long-term change is central to most of those definitions).

    Much of the material produced by technical communicators is only intended to inform–that is, be used now, and forgotten immediately afterwards. If a user needs the material again, he or she will search for it.

    This has profound implications for the approach to user documentation. We intend for users to learn certain tasks–that is, master them and permanently adopt them. In many instances, these are basic tasks that users regularly perform on a frequent basis.

    But many of the tasks that we describe are not intended to be learned. They are intended to be performed once, maybe twice, or infrequently. For example, tax-related tasks are often only performed when we must file tax returns. Such information is disposable.

    Both types of material require clear, well-presented instructions. But because the long-term use differs, our need to apply learning theory might not be appropriate. Instead, we should be applying reading theory.

    Indeed, one of Jack Carroll’s initial motivations for developing minimalism was that, when we first introduced computers, we taught everything and expected users to master everything, whether or not the material was even relevant to their needs. We taught them about RAM and ROM and all sorts of other “inside stuff” when all they needed to learn was how to start the computer and launch Wordperfect (later, Word).

    The real problem in that scenario is that we were over-teaching–and it goes back to my first two points: Someone didn’t really know what users needed to start using a computer and what they didn’t, and just stuck everything in. The people reviewing the material didn’t exercise their authority and respond, “Whoa! Why does someone who needs to enter customer data into a database need to learn about RAM, ROM, and the DOS prompt to begin using the computer for data entry?”

    (5) As far as translation and localization dictating choices for documentation: it’s a concern but should not be the driving choice. If the user benefit–and resulting support costs–are high, then the choice should always be in the favor of the user.

    And a surprising finding from the research I have performed: only a small percentage of documentation–including user documentation–is actually translated unless, like medical devices and pharmaceutical documentation, translation is required by law. Although this was admittedly a small sample, the few software cases I studied where translation was an issue, only 20 to 25 percent of the documentation was translated to another language. (The first language was not always English in this research.) The only exception was a government project, where the law prevented publication of anything that was not translated. And that only occurred in jurisdictions that had several official languages. If a jurisdiction has only one official language but a large population that speaks another, it only translates as time and resources permit.

    This practical reality has many implications; my goal is not to ignore those.

    But the matter at hand is the extent to which translation affects documentation choices. If translation is only a factor in some organizations–and for some documentation–then we cannot use that as a reason for failing to meet provide task-oriented materials. And even in those instances where we do translate, the needs of our users should always play a primary role in the decision-making process.

    • Chris Despopoulos

      Reading this comment made me consider a few things.

      First, why SHOULD users be enthusiastic about help? Help is where you go as a last resort. Are you enthusiastic about getting a root canal? So we may be asking the wrong question…

      Ok, so what we want is for users to actually USE the help when they need it — get a root canal instead of false teeth. And I think the issue (as Mark Baker points out) is that people turn to the crowd in preference to help. Again, for some domains this might be the most appropriate response. Instead of a root canal, try holistic medicine. For some (perhaps many) maladies herbs, placebos, and magic wands are superior — I’m not kidding. But there are some domains that are too specialized or complex to rely on crowd “intelligence” (mob intelligence??? Is there a difference?).

      About task- vs feature-oriented docs… No question that a list of features is a poor way to document a product. But what has come to be regarded as task orientation doesn’t sit well with me either. We need to start thinking in terms of use case orientation. More often than not, a use case doesn’t break down into a list of steps. Use cases can branch, they can nest, they can involve activities that lie outside of the product’s interfaces. What we don’t need are the steps to perform a series of GUI gestures.

      Another thing I think we need are definitions of terms. A product domain has its own vernacular and its own paradigm. You can’t come to terms with a product and not internalize these. Nothing is worse than help that says “The foo button foos a bar. To foo a bar, click Foo.” What do Foo and Bar mean? What are their dependencies? Why do I care about them? Is this even close to what I’m trying to accomplish? What we call context sensitive (actually context specific) help often lands you on a page full of these sorts of statements.

      Finally, I think we’re close to having true context sensitivity in our docs. There’s nothing to keep your docs from querying the user’s session with the product, and focusing on that field of activity. Shoot, Microsoft was doing that with Clippy decades ago. It’s in the execution… Clippy was annoying, but responsive docs don’t have to be.

      But back to the original question. If we manage to make the PERFECT product documentation, will the average user be enthused? I think not. I think the average user won’t even notice, because I think that’s a hallmark of good design (aesthetics notwithstanding). The less you notice the GUI or the docs, the more you say, “Of course it works like this, what’s the big deal?”, the better the design. And that’s the opposite of enthusiasm.

  • Saul Carliner

    P.S. Sorry for the typos in the previous post–was typing too fast.

  • Pingback: Category redefinition for tech comm? | Write Degree Communications()