Elements of Style and the documentation-guide

[Karsten Wade]

On Sun, 2004-07-04 at 06:31, Paul W. Frields wrote:
> On Sun, 2004-07-04 at 05:55, Telsa Gwynne wrote:
> [...snip...]
> > http://developer.gnome.org/documents/style-guide/locale-5.html
> > 
> > There are twenty topics covered there, with rules, exceptions,
> > bad examples and rewritten sentences. They range from some which
> > are good practice in any technical documentation to others which
> > look surprising unless you are familiar with how other languages
> > say things. 
> [...snip...]
> 
> Excellent points all, and thank you for the link. This guide mentions a
> lot of ways to correct the poor style that afflicts a lot of Linux
> documentation on the Web. I glanced over the GNOME guide and found
> references to a number of peeves which it is designed to prevent. I
> don't see an easy way of including its contents other than in whole
> (which is not a problem given that it is licensed under the GFDL), but
> since they're very complete in their current form that might be the most
> advisable strategy. Perhaps this calls for a "part" organization in a
> more comprehensive Fedora Style Guide, which might wrap up several other
> guides such as the GNOME guide you mention.

Perhaps it should be "Fedora Documentation Style Reference Set" ... or
something similar which denotes a collection of style references that
are considered canonical or argument-ending references.

> I picked EoS mostly due to its copyright status in the U.S., and, I have
> to admit, my personal feelings for the book. There didn't seem to be
> much in it which would be odious to anyone, but certainly it's still
> merely a "guide," not "law." :-)

Agreed.  One of the important things about knowing style rules is
knowing when to break them, with intention. 

- Karsten
-- 
Karsten Wade, RHCE, Tech Writer
this .signature subject to random changes
http://people.redhat.com/kwade/
gpg fingerprint: 2680 DBFD D968 3141 0115  5F1B D992 0E06 AD0E 0C41