Comments on: The Kind of Documentation Users Really Want

By: Tim Mantyla

Tim Mantyla — Tue, 08 Jul 2008 16:34:26 +0000

It’s not always easy to determine what kind of user assistance format, publication or website-style help to use.

I interviewed as many of the potential readers of the online sales training & reference guide before writing it. That way I found out what they wanted and needed “from the horse’s mouths.” They’re the subject matter experts (SMEs) on what they want and need to know. (Company officers may have a somewhat different idea of what they need staff to know.)

From their answers, and the company’s requirements, I determined that a website-style help system would work best.

Sometimes you have to imagine you’re a reader or two–or more. Preferably imagine a range of readers/users, from the least skilled and savvy to the most.

If you can’t imagine being a reader, ask someone you know with a good imagination–perhaps a writer or graphic designer (or a good liar!) to pretent to be your reader, then ask your questions.

In any case, asking *someone* to be a potential audience member is better than just writing for people you’ve taken less than a minute to stereotype.

I don’t mean stereotyping in the sense of prejudice or racial/sex/religious discrimination. Stereotyping is a way of categorizing people, things and situations into easy mental compartments in order to understand, analyze and quickly deal with them. It’s a psychological mechanism we all use, almost all the time–no matter our skin color, religion or whatever. Without stereotyping, we would all be asking countless questions to grok everyone and everything in such detail that we’d get no work done and might not even have time to get food!

It follows logically that we always have to stereotype our readership to some degree. It’s a matter of what degree of detail we have time, budget and attention span to analyze the audience.

By the way, this would be a good topic to cover in a style guide or publication guidelines.

Tim Mantylas last blog post..Publication guidelines are more useful than a style guide

By: Tom

Tom — Mon, 23 Jun 2008 13:11:04 +0000

I agree with you in part, but format does make a difference. My experience with help goes like this. I create an online help file, because people like to search quickly for a task. Then someone asks if there’s a printable version of the online help. So I create a manual. Then someone gawks at the size of the manual and asks for a concise version, so I create a quick reference guide. Then some users say they don’t learn from written instructions and want to see the process. So I create video tutorials. It would be nice if I could just point them to one file, but that solution doesn’t work in my experience.

By: avi

avi — Sun, 22 Jun 2008 07:35:25 +0000

Users want accurate, complete and helpful documentation. This is why I tossed single-sourcing years ago.
If the documentation is helpful, the users doe’t mind reading it on a PDF, a CHM, MOSS, or on an email from me (“the doc is not approved yet, but I’ll let you read these several pages only because you’re such a great contributor to the documentation I write”).

avis last blog post..הבעיה עם הטיפול בגלעד שליט

By: Useful Stuff for Tech Writers « Orion Spur

Useful Stuff for Tech Writers « Orion Spur — Sat, 21 Jun 2008 21:26:46 +0000

[...] The Kind of Documentation Users Really Want [...]

By: Deb Lockwood

Deb Lockwood — Thu, 19 Jun 2008 14:32:43 +0000

Tom,
I thought this was a great post; informative, thought provoking, helpful. I’m forwarding the post to some other folks in our company who have been talking about the same topic. Thanks for your devotion to the profession of technical communication!
Deb

By: End User Surveys - The Content Wrangler Community

End User Surveys - The Content Wrangler Community — Wed, 18 Jun 2008 14:08:52 +0000

[...] Hi Rebecca! I saw your question earlier. I don’t really have a good answer for you and was hoping someone else would answer it. We do try to collect user feedback but rarely get much response. Most users don’t comment at all. A few complain of very specific information they were looking for and couldn’t find. Occasionally our service, training, or support people come back with stories from on-site visits indicating the users liked our online help. Today I saw an interesting post on Tom Johnson’s blog that talks about users’ preferred ways to learn software. Reading the blog reminded me again of your question, and I thought you might find it helpful. Here’s the link –> http://www.idratherbewriting.com/2008/06/15/the-kind-of-documentati… [...]

By: erica

erica — Tue, 17 Jun 2008 00:58:21 +0000

We plan to do video tutorials (usually about 2 minutes long), cheat sheets with one set of steps per common procedure, and a compiled help file with all the details. They do ask me to export the CHM out to PDF though we all know no one uses it anyway.

By: Scott

Scott — Mon, 16 Jun 2008 22:39:47 +0000

Tom,

Sometimes it frightens me how in sync our minds our. I wrote a post in a similar vein on the weekend!

This is great post, though. My take: the deliverables will vary based on the product and the audience. There’s really no one-size-fits-all solution.

By: A Winner, 76 Years Later

A Winner, 76 Years Later — Mon, 16 Jun 2008 19:44:52 +0000

[...] Tom Johnsons last blog post..The Kind of Documentation Users Really Want [...]

By: Joe

Joe — Mon, 16 Jun 2008 19:20:48 +0000

Unfortunately, I don’t get a lot of interaction with my users, which, I feel makes the quality of my documentation suffer. I know what they use the appplications for (most of them anyway, I also document a lot of back-end systems that have little or no user interface), but not necessarily how they use the applications. Most of what I get is through the filter of a marketing person, who usually feel that “more is better.” Holly’s example of users requesting a one-page cheat sheet mirrors what I got when marketing reviewed my QuickStart Reference Guide, which is basically a two-sided one page reference card in column format. It is exactly what it says it is – a QuickStart Reference Guide. Something to help the user get started in a hurry. If they want in-depth information, they can look in the User Manual, or online help both of which are provided with the application. But, my marketing guy wanted to know why I didn’t have more information, more screenshots, etc. To put in all the information he wanted would have defeated the purpose of the QuickStart.

Anyway, I’ve found users to be of three types:

1. They try to learn the application on their own, and only look in the manual when they can’t figure something out.

2. They try to learn the application on their own, and use the online help only when they can’t figure something out.

3. They try to learn the application on their own, and the first time they get stuck, they call Tech Support.

I’ve hardly ever come across a user who consulted the manual first.