Best Help Authoring Study

Help trends are something that are rarely documented. Help authors do what they feel works for them and over time, a general consensus develops. At times, it is necessary to challenge of confirm that consensus. Recently, someone in Israel wrote to me and explained that the documentation manager was insisting that they include graphics in the online help. This technical writer wanted to know if I knew of any surveys or studies that discussed the best or accepted practices.

After a bit of research, I found there was little that offered any conclusive evidence from the experts – help authors who have been developing help for years and so WritePoint decided to sponsor one. Over 160 people responded to the survey call and the results were quite interesting.

Do you use graphics in your help?

The numbers were surprising here for a variety of reasons but the explanations were much more in line with what I expected. The results were as follows:

  • Yes: 49.06%
  • No: 14.90%
  • Sometimes: 36.02%

I had expected many more “no” answers. As a rule, I strongly advise against graphics in help and give a whole list of reasons why. Some were mentioned in the responses, while other comments were intriguing. Here are a few that I thought were interesting:

  • “There are two main reasons why we don’t use full screens: 1) our help opens alongside the app, so often the user is already looking at the screen, and 2), the way our help opens gives us very little screen real estate.”
  • “We single source our PDFs and help systems. Since we recently switched to Frame and can make screen shots conditional, we will remove screen shots from the help.”
  • “Help is only accessed from the screen, so a screencap is redundant. Only confusing dialogs, or sometimes pieces of screens, are included for clarify.”

These were some of the reasons I have traditionally used to explain why I am against the practice of putting screen captures in help. Almost 15% of the respondents agreed with me while more than 49% disagreed. They too explained their reasons:

  • “Diagrams often convey concepts better to visually oriented readers, screen captures are required when GUI elements don’t have simple labels.”
  • “As a guide for users and to assure them they are on track with the written instructions.”
  • “Help may be used offline for training.”
  • “To reinforce the written instructions with a visual clue.”

And the simplest and perhaps most important of reasons for including them, noted one participant was: “They help the user.”

Another 36% responded that they sometimes put graphics in, and gave reasons for this as well. Overall, the goal in all cases seems to be the same: to give the user the most useful help. What it comes down to, then, is a disagreement on how users use help and how we as help authors can assist them. There is no question that users are more likely to look than to read. No question that a graphic “speaks” to them more than a long paragraph.

Although I launched the survey to assist another technical writer, I am reconsidering my longstanding opposition to graphics in help. Over the 15 or so years that I have been developing help systems, I believe the user has changed. Programs have become more simplified and graphically appealing. I suppose, to some extent, the help must follow as well.

There are still times when a screen capture is simply a nuisance, but perhaps the group that most accurately answered the question for “best practices” belongs in the “Sometimes” category, leaving it to the help authors to determine when that sometimes falls in the “Yes” area, and when, as it often does, in the “No” area.

You can find complete results of the Help Authoring Survey on the WritePoint website.