Re: Writing simple procedures

["Susan W. Gallagher" <sgallagher -at- STARBASECORP -dot- COM>]

> 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.
> ...

> or

> 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.

> --
Glenda,

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
was invented!

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!

Sue Gallagher
StarBase Corp, Irvine CA
sgallagher -at- starbasecorp -dot- com