Date: Thu, 14 Jun 2001 00:37:16 +0100 From: Nik Clayton <nik@FreeBSD.org> To: Chern Lee <chern@meow.osd.bsdi.com>, <freebsd-doc@freebsd.org> Subject: Re: Style/Grammar/Writing Guidelines Message-ID: <0106140037160N.37769@clan.nothing-going-on.org> In-Reply-To: <Pine.BSF.4.31.0106131439170.43965-100000@meow.osd.bsdi.com> References: <Pine.BSF.4.31.0106131439170.43965-100000@meow.osd.bsdi.com>
index | next in thread | previous in thread | raw e-mail
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
On Wednesday 13 June 2001 10:53 pm, Chern Lee wrote:
> I'm helping read over the handbook in order to prep it for its next
> edition of the printed version.
>
> I feel this applies to not only the printed version, but also the
> handbook as a whole, and any other documentation we have.
>
> In reading the first two chapters, I've noticed that a lot of it is very
> loosely written--especially the second. This occurs throughout the
> handbook.
True. This is because of the large number of contributors.
Before this develops into a huge thread about style guides and such, I've
got a couple of questions.
1. How many of the buyers / reviewers of the Handbook said that they
didn't like the tone.
vs.
2. How many of the buyers / reviewers said that they really, *really*
wanted to see a decent index?
We can invest a lot of time in coming up with a style guide. And unless
someone volunteers to review every single doc commit for style, I can
guarantee that it won't be strictly followed. We'd need a Bruce Evans for
doc/, basically[1].
If WRS is going to make this someone's paid job then it's a different
matter -- but I think that's the sort of commitment it will take to make
this work.
> Does anyone know of a style/grammar/writing guideline document for the
> doc project?
The closest thing we have to a style guide is
http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/writing-style.html
It could certainly use some additions. But I fear that the big problem
will be sticking to the guidelines (particularly as, the longer they
become, the more likely it is someone will think "Blow me, I'm not reading
that just so I can contribute some documentation")[2]
Having said all that, I'm not in any way against the development of more
formal guidelines. I just don't think they'll be the panacea they might be
expected to be, and we could be focussing our limited energies on efforts
that will be more useful to the readers (like, for example, an index).
N
[1] Bruce, bde@freebsd.org, seems to have limitless amounts of time to read
every single commit to FreeBSD, and an encyclopedic knowledge of C and the
preferred FreeBSD coding style. Many is the commit to the src/ tree that
starts "Brucify this code".
[2] I am aware of the irony in re this statement and the size of the rest
of the primer. . .
- --
FreeBSD: The Power to Serve http://www.freebsd.org/
FreeBSD Documentation Project http://www.freebsd.org/docproj/
--- 15B8 3FFC DDB4 34B0 AA5F 94B7 93A8 0764 2C37 E375 ---
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.6 (FreeBSD)
Comment: For info see http://www.gnupg.org
iEYEARECAAYFAjsn+SwACgkQk6gHZCw343W3LgCeOy+dtsQb2syWC+lVrmqePuVX
TQAAoI5tu4hp2e5Dsrw06jWdaa7DS7AE
=rTGn
-----END PGP SIGNATURE-----
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
help
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?0106140037160N.37769>