cvs commit: doc/en_US.ISO8859-1/books/handbook/disks chapter.sgml

[Tom Rhodes]

On Sun, 28 May 2006 21:37:58 +0200
Marc Fonvieille <blackend at FreeBSD.org> wrote:

> On Sun, May 28, 2006 at 06:33:25PM +0000, Remko Lodder wrote:
> > remko       2006-05-28 18:33:25 UTC
> > 
> >   FreeBSD doc repository
> > 
> >   Modified files:
> >     en_US.ISO8859-1/books/handbook/disks chapter.sgml 
> >   Log:
> >   Update the DVD-RAM section a bit.  This avoids the usage of "you", "we"
> >   and things like that, which is consistent with the rest of the documention.
> >
> [...]
> 
> Using grep on chapter.sgml gives about 250 "you" and 35 "we"
> (in the related section: 29 "you" and 8 "we"); I think there's a
> confusion with the use of "I" or other familiar wordings.
> 
> You changed the active voice of "You have to enable DMA access for ATAPI
> devices, this can be done in adding the following line to the
> /boot/loader.conf file:" to the passive voice, Ok[1] but you have to
> also change the same sentence which appears at the beginning of a
> previous subsection (17.7.2) to be really consistent.

If you're trying to set a precedent, I'm all about it; however,
I think you should change this subject first.  This entire
discussion is getting dangerously close to a situation where
we need to get general agreement.

Personally, I see no real problem with Remko's change, other
than it changed the "grammatical style" of the section.  This
doesn't bother me because, if you read over many (too many) of
the sections I've written, I push the idea of not addressing
the user.  Either way can be correct, but I dislike adressing
myself, or the user.  It also opens the doors for "sexist
language."  I.e.: "his computer" or "she put the disc in the
drive."

We have done a good job at restricting sexist language:

%find . -type file -name "*.sgml" | xargs grep "[[:space:]]her[[:space:]]"
./config/chapter.sgml:    When a user installs his or her <filename>crontab</filename> file, they
%find . -type file -name "*.sgml" | xargs grep "[[:space:]]him[[:space:]]"
./mac/chapter.sgml:     exactly how everything works may find him or herself going
./multimedia/chapter.sgml:      <groupname>operator</groupname> group will allow him to use
./security/chapter.sgml:        him in the act.</para>

But currently we mix both passive and active and I would like
to see a choice made and we stick to it.  Looks better, more
professional, etc.  Note, I would not be too happy with
using active since I have at least 3000 lines which use
passive.  Note I say "at least," there are probably many MANY
more.

Personally, I have yet to see a really good argument for using
one over the other.

Thanks,

-- 
Tom Rhodes