Re: Style Guides?

[Andrea Magers <Andrea_Magers -at- NOTES -dot- PW -dot- COM>]

This is confusing, but I think Don writes:

mpriestley -at- vnet -dot- ibm -dot- com writes:

>Don M. Chaffee (dchaffee -at- WORLD -dot- STD -dot- COM) writes:
>>Apple Style Guide.  They're the only computer company I've run across that
>>has even bothered to write a style guide.  If Microsoft has one, their
Write in the present tense, active voice, indicative mood.
>>  "The system displays the dialog box"
>>  not
>>  "The dialog box appears"

I don't like either.  As for the first example, "the system displays" takes
the "you" out of "user".  What I mean by that is, that phrase does not give
the user responsibility for their actions. My example in a user guide is:

Press [F2] to display the dialog box.

In this command, the "you" is understood (You press [F2]...).
after all, aren't we talking/writing to our users?  We should give our users
the opportunity to take responsibility for their actions, instead of telling
them that "the system" does everything for them. Let's provide our users with
power, not take it away from them (give it to "the system") and confidence,
not insecurity and dependence! Maybe I'm carriying this into my own
philosophy (okay, I am), but the more people take responsibility for their
own actions, the less they blame others. How many times have you heard
someone say that it's the computer's fault? How about those people who have
most everything done for them by someone or something else?  They aren't very
appreciative and they complain a lot, but most of all, they can't take
responsibility for their own actions!

I must clarify that I believe discussing what "the system" does has its place
(ex: a theoretical document), but it does not belong in a user guide.  "You
attitude" belongs in a user guide.

As for the second example, I don't feel that technical documentation should
be associate with magic (appears).  There's certainly nothing magical about
writing it!

Andrea_Magers -at- notes -dot- pw -dot- com