TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: Writing simple procedures From:Sue Heim <SUE -at- RIS -dot- RISINC -dot- COM> Date:Fri, 5 May 1995 08:35:38 PST
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...
Research Information Systems
Email: Sue -at- ris -dot- risinc -dot- com