Re: Writing simple procedures

[Sue Heim <SUE -at- RIS -dot- RISINC -dot- COM>]

Sue Gallagher writes:

> Whether or not something is "too obvious" to document depends
> very much on audience analysis. If the product you're documenting
> is targeted at the novice user -- or if you're writing instructions
> about the "bottom level" (e.g. the user interface itself) -- then
> you have to assume that *nothing* is obvious and spell out every
> mouse click and keystroke.
<lots of snipping>

I definitely agree -- your target audience should be the main
consideration. The only time I ever really ran into problems trying
to figure out what level to write to was when I was documenting a
software product that anyone from a complete novice to an experienced
user could use. We settled on a compromise (since we didn't want to
annoy the experienced users, but also didn't want to lose the novice)
but clearing stating up front what the conventions in the manual
were. So, "clicking" meant to move the mouse over a button or tool
(or checkbox or radio button) and depressing the primary mouse button
(and yes, I also explained what a primary mouse button was). Then, in
the docs, I could be more succint.

BTW, I now insert the caveat that the manual is written with the
understanding that the user has basic understanding of DOS commands
and Windows functionality. It doesn't always help, but still...

...sue
---------------------
Sue Heim
Research Information Systems
Email: Sue -at- ris -dot- risinc -dot- com