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

[Tom Rhodes]

On Mon, 29 May 2006 09:12:35 +0200
Marc Fonvieille <blackend at FreeBSD.org> wrote:

> On Mon, May 29, 2006 at 08:17:39AM +0200, Remko Lodder wrote:
> > On Mon, May 29, 2006 08:08, Marc Fonvieille wrote:
> > > On Sun, May 28, 2006 at 09:46:38PM +0200, Remko Lodder wrote:
> > >> Marc Fonvieille 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.
> > >> >
> > >> >Marc
> > >> >
> > >> >[1] Many persons think the passive voice should be replaced with
> > >> active
> > >> >voice, but no one is really affirmative on this point, an
> > >> interesting
> > >> >point of view can be found at http://www.spinellis.gr/blog/20060316/
> > >> >(dds@ blog).
> > >>
> > >> OK, i am fine with boths ways (although you can see my preference
> > >> with this commit): do you think we can workout something for doc@
> > >> so that we have a guideline or something?  The one thing that I do
> > >> want to have is having documents being consistent with eachother in
> > >> the way they address people etc.
> > >
> > > As I previously said there were 2 instances of the same sentence on
> > > that
> > > page.  I just wonder why you changed one and not the other since you
> > > stated you did it for consistency.
> > >
> > > Marc
> > >
> > 
> > I only changed it there because i was actively translating that part
> > and saw the text, and we tend to only change things when you are
> > working on it anyway.
> 
> So there's a problem in your commit 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."
> --
> 
> Where's the consistency when you do not even check the rest of the
> page?  You are also stating there's a convention about the non-use of
> "you" and "we", where's that "guideline" in the FDP?
> 
> To sum up you said "that wording is not good", so you change the wording
> but you do not change the same wording 20 lines above, and you use
> "consistency with the rest of the documentation" as reason of your
> change.  If you want to be consistent, please be consistent.
> I'm not against the change, I'm against the fact you do not really think
> twice before changing a thing.

I'm in full support of Remko's change and hope that he continues
to work on this chapter.  It needs a set of eyes placed on it
and I'm happy he's doing it.

Remko, keep up the good work.

-- 
Tom Rhodes