Re: Personification of gadgets and thingamabobs

[Ben Kovitz <apteryx -at- CHISP -dot- NET>]

Lauren Merritt wrote:

>I'm working with one of those ponderous, highly technical documents that
>make my brain hurt. Right now I'm stalled against the following
>sentence:
>
>"To fire the triac pulse at the proper time, the ASP driver must know
>which phase powers each lamp block."
>
>I know this is an ugly sentence when taken out of context this way, but
>that's not what hurts right now. I'm really trying to avoid the
>personification of this ASP driver thingie, and just can't seem to get
>around it.
>
>Does anyone have general suggestions on avoiding personification? How
>hard should I try?

Interesting question!  (And that second question is the one on every
professional's mind.)

I really don't like the use of "know" to mean "be in a state that
corresponds to", but of course the latter phrase is way too
theoretical for most technical documents.  I don't like "know"
because it's metaphorical: as you say, it personifies something
that just is not a person.

But what alternatives are there?

   "the ASP driver must be notified of..."

   "the ASP driver must be informed of..."

   "the ASP driver must have a record of..."

Each of these draws upon words formerly used only to mean actions
involving human beings and human consciousness.  To speak about
the kinds of states and relationships that occur frequently in
software, people have simply added new senses to these words that
don't imply consciousness.  That's often how jargon evolves:
people invent new, narrowly defined senses for words that already
exist and mean something similar or more general.

Perhaps the same process is now happening to the word "know".
Certainly programmers say "know" in the software-only sense all
the time.

However, at this stage, I think that's still a very informal
usage--too informal for most technical documents.

So here are two approaches to search for a substitute word:

1. Choose a dead metaphor rather than a live one.  So write
"notified", "informed", "recorded", etc.

2. Describe the situation in words that have to do with the
concept of "state", either the state of the ASP driver or the
state of some part of the ASP driver that you explicitly define
previously.  The word "state" itself, though, is too abstract for
most purposes.  So "the ASP driver must be configured for...",
"the ASP driver's configuration file must contain...", "the ASP
driver must be set up for...", "the ASP driver's current settings
must match...", "the ASP driver must store..."

The notion of "containment" often works in a slightly
metaphorical but perfectly acceptable way that doesn't bother
anyone.  You can say that the file must "contain" the powering
phase for each lamp block.  Of course, the file doesn't literally
contain those phases!  The file merely contains bits whose state
corresponds to the phases.  But because you're talking about a
file, readers naturally interpret all that comes as a description
of states, without ever having to consciously think about and
distinguish all these subtleties.  Notice that without a word
like "file" or something like it, the word "contain" would seem
strange.

If for some reason you want to be completely literal, though, you
can say, "the ASP driver's configuration file must contain a
record of..."


One other note: the passives in my examples are necessary only if
there are many different ways that the ASP driver could be
notified of the powering phases for the lamp blocks.  If there's
only one way that the ASP driver can get this information, then
you can be even clearer by writing something like: "To fire the
triac pulse at the proper time, you must have configured the ASP
driver for each lamp block's power phase (see section X.XX)."

--
Ben Kovitz <apteryx -at- chisp -dot- net>
Author,  _Practical Software Requirements: A Manual of Content & Style_
http://www.amazon.com/exec/obidos/ASIN/1884777597
http://www.manning.com/Kovitz


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=