style bits (was Re: [Doctable] Documentation Writing Process)

[John Fleck <jfleck inkstain net>]

Folks - Whoa. Lots going on in Dan's missive. I'm breaking my response
into bits to keep it all straight.

The style bits:
On Sun, Jan 21, 2001 at 03:01:48PM -0800, Dan Mueth wrote:
>
> 1) The GNOME Style Guide - This should explain the GNOME writing style
> including use of markup, appearance of figures and screenshots, use of
> language, and other style to help writers produce good documentation and
> to allow the body of GNOME documentation be self-consistant.  (Currently
> under development by John Fleck, Alexander Kirillov, John Gilger, Pat
> Costello, and John Sheehan.)
> 
> 2) GNOME Word List - This should list all the terms we standardize on,
> capitalization of them, hyphenation, and possibly definitions where it is
> not obvious or there is a possibility for confusion or use of a term for
> two different meanings.  This could be part of the Style Guide, although
> it may be easier to keep them seperate initially.  (Under development by
> style guide team.)
> 

I'd argue for keeping the word list in the Style Guide - the fewer
places we need to hunt for things the better. It will be its own
chapter and live on the web.

> 3) Example documentation/tutorial - We need one or more example documents
> which illustrate good and bad writing and a tutorial which discusses
> specific points in the example documents.  We might want to arrange this
> as "A Tutorial on Writing GNOME Documentation" and put the example
> documents in appendices.  Then the main tutorial would be a discussion of
> these example documents.
> 

What would be the relationship between this and the templates? Should
rewriting the templates be included in this list, or is 3) above the
same thing? The style guide is shaping up to be very tutorial in
nature, peppered with "bad" and "good" examples (it's amazing how easy
it's been for me to find bad examples in my own writing :-) This
tutorial sounds like a helpful adjunct to the Style Guide - it could
be closely tied to the examples used in the Style Guide itself,
expanding on them to provide a more complete illustration.

Cheers,
-- 
John Fleck
jfleck inkstain net (h)
jfleck abqjournal com (w)
http://www.inkstain.net/fleck/
http://www.abqjournal.com/scitech/