Re: [Bug-gnupress] What voice do we use?

[Simon Law]

On Mon, Apr 28, 2003 at 11:00:05AM -0400, Lisa M. Opus Goldstein wrote:
> 
> 
> Actually, Paul, you pointed out a big problem.  The voice for the
> manual has become rather scattered as different people made updates
> and added sections.  This is especially noticeable in the "definitions"
> sections. 
> 
> In general, I believe that we should avoid using any language to
> represent the writer.  99% of the time this is easily done by
> restructuring a sentence.  If there is a need for this, such as
> explaining why a decision was made to follow one coding style and not
> another, then the GCC Steering Committee can be introduced as the
> agent of action, rather than an amorphous "we".
> 
> It is also best to avoid direct references to the reader/user.  It is
> too "chatty" a style for a written reference manual.  Most of the time
> the need for directly addressing the reader can be avoided by
> rewriting the sentence with a different structure.
> 
> If second person cannot be avoided, it is probably best to refer to
> the third person "the user", rather than "you".

        I am considering this, and have mixed views.

        I am quite the traditionalist, and have been taught that
computer manuals ought to be written in third person imperative.  Yet,
this wording sounds incredibly stuffy and is often difficult to parse.

        I find that most of the manuals written by hackers to hackers
are set in the first person imperative.  This results in a friendly,
chatty style, where one person is trying to impart knowledge to another.
This makes the manual far more readible.

        In an informal survey of a sample of GNU manuals [1], it appears
that they all use this first person imperative style.  I propose that we
stick with that instead.  (I believe that that best selling publisher
O'Reilly also uses this style [2].)

Simon

-----
[1] I surveyed Autoconf, Automake, GCC, Emacs, Texinfo, GNU libc, and Bash.

[2] http://letters.oreilly.com/graphicdesign_0401.html