sophisticated users? (long) -Reply

[Lisa Comeau <COMEAUL -at- CSA -dot- CA>]

Rowena wrote: (without the snippage)

"... trim our user documentation down to "essentials" because our users are "too sophisticated" to require ... complete step-by-step instructions."

I say:
>>Who decides what the "essentials" are? Those who create the program, or those who use it? I think that the person who has never seen the program before is in a better position to determine what the essentials are.

RH
 "I made a decision  to write instuctions in full sentences using bold type to identify buttons, menus, menu commands, and other inputs...
...some developers... would like to see instructions such as "Load the Toolkit," rather than "From the <b>Tools</b> menu, select <b>Load Toolkit</b>,"where we assume that the user has played with the GUI and
figured out how to load the Toolkit by themselves."

LC
>>Which is EXACTLY what a manual is NOT supposed to do...assume. A manual is supposed to make navigating and using the program easier, and give the user answers to questions. If I had the time to sit and play with a program, I would, but since I *don't*, I want the manual to tell me.  Even if I have been using XYZ Program for 2 years, when I walk away from the program for a month or two, I may forget about where everything is and how to get there. 

RH
" The documentation shouldn't be written to satisfy people who are already familiar with our software, it should be written to satisfy people who've never used it before."

LC
>>EXACTLY!

RH
"However, programmers are programmers, and I don't want to ignore feedback saying that the documentation is too wordy or talks down to our users."

LC
>>Who is responsible for getting "letter bombs" when the manual doesn't give the right amount of info? You don't have to *ignore* their feedback, (you've already listened to it and thought about it) but you *do* need to look at what's most effective.

If you are creating the manuals for print, you could use symbols to denote beginner, intermediate, and advanced tasks. Outline at the beginning that this format is in effect, and use substeps within the manual.

For example:
A=advanced  I=intermediate  B=beginner

A-1)Load the toolkit
I--a)choose Tools...Toolkit
B---i)from the tools menu, choose toolkit

of course, you'd use symbols instead of the letters, and you'd probably end up with more pages than usual, but for * some * manuals, this works.  At leats you're getting ALL users covered here.

Why not approach these programmers with several samples of what you feel are *good* and *bad* documentation. Go into it armed and dangerous, and make sure you calmly approach the subject of what is effective documentation style. If you show them why *not* to use this format they propose, they may be a little more willing to compromise.

Lisa Comeau
IS Super-User/Trainer
Certification and Testing Division
Canadian Standards Association
Rexdale, ON
comeaul -at- csa -dot- ca