No need to mention the actor?

[Arthur Comings <atc -at- CORTE-MADERA -dot- GEOQUEST -dot- SLB -dot- COM>]

Jim Grey said:

> Regarding the "The system displays the dialog box" vs. "The dialog box
> appears" debate:

> Everything the system does, the system does.  So there's little need to
> repeatedly remind the user.  So when a dialog box appears -- of course
> the system put it there.  It's no stretch to figure that out.  If I
> always attribute the system with all its actions, soon most sentences
> begin with "The system".  To avoid this, I obscure this actor in the most
> common instances, and one of those is the display of prompts and/or windows.
> Thus, "The dialog box appears."  (It's also shorter.)



If you're lucky enough to be documenting a product where the system is
doing everything directly, I can see what you mean. For most of our
writing, however, things are more complex. The master program I'm
documenting has many applications within it, for example.

I still believe it's important to remember that what's obvious to us is
rarely so obvious to our readers. In your application where the system
is doing everything, your audience of system administrators clearly
wouldn't need hand-holding.

But I've seen enough of writers and programmers easily agreeing with
each other that only a fool could misinterpret something, so they can
let precise writing slide. The more predictablity and comfort I can
build into a description of a process, the better -- to prepare the
reader for the tough parts of the program. And having things "appear"
somehow chips away at that. For me. Obviously not for you.

And I think we're still not communicating, because I can promise you
that most of my sentences don't begin with the name of the product I'm
documenting, or its sub-applications. Most of my sentences are
explaining concepts and standards of one kind or another, or telling
the user what to do. When some part of the program does something, I
say so.

Arthur