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:"Susan W. Gallagher" <sgallagher -at- STARBASECORP -dot- COM> Date:Thu, 4 May 1995 10:15:24 -0700
> Sue Gallagher wrote:
> > I think that part of the problem you're having with the
> > sentence is that it combines two distinct steps (selecting
> > and opening). If this is a part of procedural text (steps),
> > you may want to break it out.
And Glenda Jeffrey wonders...
> I have a question about this -- at what point is something so
> obvious that you don't want to break it out into two steps?
> For example:
> 1. Move the cursor to the XXX toolbox.
> 2. Click on the YYY icon.
> 1. Click on the YYY icon in the XXX toolbox.
> Is the first form too obvious? It seems so to me, but then
> again, you want to write these kinds of things to the lowest
> common denominator, right?
> I guess it's a matter of taste, but if anybody has opinions
> one way or the other, I'd love to hear them.
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.
If, OTOH, you product targets a more sophisticated audience
(developers, experienced word processors/desktop publishers,
or other similar audiences), you have to assume that they
know how to do some things (like open a file).
Most often, in the products I write about now, I have to assume
a certain level of expertise. I have so much *else* to say
that I can't afford to document the basics too. The book
would become a true behemoth. So if I reference an obscure
procedure within the operating system or interface, I point
the user to the help file or system user manual that contains
the appropriate background info, I don't "reinvent the wheel".
But -- back a few years ago when I was developing "basic"
courseware for DOS applications (and, later, the "brand
new" Windows stuff) I assumed that the user had never even
seen a computer before and broke everything down to the
keystroke/mouse click level. It was my job to not only
reinvent the wheel, but to show exactly *how* the wheel
So, it comes back to those words we live by...
>>>It depends on the audience<<<
Excuse me now, I have to throw another two cents in the kitty!
StarBase Corp, Irvine CA
sgallagher -at- starbasecorp -dot- com