Elements of Style and the documentation-guide

[Telsa Gwynne]

On Wed, Jun 23, 2004 at 01:31:11PM -0400 or thereabouts, Paul W. Frields wrote:
> 
> In addition, or as an alternative, to EoS, perhaps there should be some
> guidelines that have been useful to the Red Hat staff in preparing their
> official RHL and RHEL documentation over the years. I have found those
> guides consistently clear, concise, and informative, and I would hope
> that FDP products would be of similar quality. By comparison, a lot of
> the documentation on the Web is poorly written, and often lapses into
> informalities, colloquialism, unhelpful jargon, and vague generalities.
> On the other hand, in many cases those materials will form the basis for
> future FDP work, so FDP content guidelines might be very useful as time
> goes on.

I have a copy of Elements of Style. I am not over-fond of it,
but that might just be because I am from the UK and thus more
used to the Oxford Guide to Style and Fowler's Modern English
Usage. Or it could be because I regularly do things of which
EoS disapproves :) 

One thing that Elements of Style doesn't have, which might be
worth bearing in mind, is detail on how to write for translation.
We have a section about this in the GNOME Documentation Project
Style Guide (that title, btw, is probably a good example of how
not to write for translation: five might-be-nouns, might-be-
something-else words in a row :)) 

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. 

I believe there are sister mailing lists to this one which are
for translators. They may have other suggestions to add to that
lot. Or there may be a more well-known one. I just know about
this one because it's a Gnome one. 

I assume it is likely that at least parts of the documentation
written by people on this list will end up being translated. So 
if you are looking for guidelines, it might be worth bearing
these guidelines in mind too.

Telsa