sophisticated users? (long)

[Rowena Hart <rhart -at- INTRINSYC -dot- COM>]

Hi folks,

Usually I appeal to members of this list for technical assist-
ance, something which has proven to be a marvellous
resource.  Now I have a slightly more personal question
to ask.

I work in a software development company, and recently
ran facefirst into a cream pie -- the pie, in this case, was
the debate about whether we can trim our user documen-
tation down to "essentials" because our users are "too
sophisticated" to require background information (in this
case, complete step-by-step instructions).

The root of the problem seems to be the writing style I've
chosen for our documentation.  I made a decision (based
on what I saw other software companies doing with their
documents) to write instuctions in full sentences using
bold type to identify buttons, menus, menu commands, and
other inputs.  An example of this would be "From the
<b>Edit</b> menu, select <b>Merge</b>."  I usually tie
these step-by-step instructions to a task that the user
needs to complete.

The argument from some developers in the company is that
our users are "too sophisticated" to be led through a GUI or
process from the beginning like this.  What they would like
to see are 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.

My instinct and professional trainging says I shouldn't just
blindly follow our developers when they request a change in
the style or presentation of our documents, especially if their
only reason for requesting a change is "That's the way I like
to see it done" ?

Yes, I am familiar with the rule "satisfy the user/client" and I
am trying to do that.  I don't think that our developers are our
users/clients.  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.
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.

Do you think I should drop the full sentence instructions and
try something like "Edit --> Merge" ?  This would satisfy our
developer's desire for brevity, but it isn't exactly elegant.

Any suggestions?  If you've developed a particular style-based
solution, could you send me examples?

Thanks again, folks,

Rowena  :-)


---------------------
Rowena Hart
Technical Writer
Intrinsyc Software, Inc.
http://www.intrinsyc.com