Re: sophisticated users? (long)

[Steve Pendleton <SPendlet -at- COGNEX -dot- COM>]

>whether we can trim our user documentation down to
>"essentials" because our users are "too
>sophisticated" to require background information (in this
>case, complete step-by-step instructions).

It's common to be pressured to omit introductory
or procedural text because someone thinks it
is unnecessary for the audience. And sometimes
skipping the basics is appropriate or unavoidable;
and sometimes it is excruciating when present.
But normally, the document should provide a complete
inventory of functionality, judiciously abbreviating
the genuine "common knowledge." Arguments that
might help:

- The number of potential customers NOT among the
  cognoscenti is larger than those already in-the-know.
  Skipping the basics can kiss off potential sales.

- Sophisticated users actually do need to be able to
  confirm that something that seems rudimentary really
  does fit their expectations. They trust the hard stuff
  only if the simple stuff is bang-on.

- In many small companies, the writer doubles as QA.
  The programmers who want you to blow off the basics
  typically blow it off themselves. You'd be shocked
  how often the GUI-level stuff is fubar. Writing and testing
  the so-called "basic procedures" can turn up some really
  really embarrassing bugs. A complete "inventory" also often
  turns up documentable facts that even the expert user would
  consider unintuitive or unpredictable.

In practical terms, writing is triage. The real expert might
succeed even if the book is wrong; the person in the middle
might make it with a good book and fail otherwise; and the
rank beginner might need more than you have time to supply.
I'm always pressed for time, so I generally aim at the middle.

Steve Pendleton
Technical Writer DeLuxe