Re: GNOME Documentation Style Guide

[David Merrill <david lupercalia net>]

On Thu, Jul 05, 2001 at 11:09:15PM -0400, David Merrill wrote:
> On Mon, Jul 02, 2001 at 09:45:36PM -0600, John Fleck wrote:
> > Folks -
> > 
> > I'm happy to submit for your consideration the first draft of the
> > GNOME Documentation Style Guide:
> 
> I've forwarded this information to the ldp discussion list. We also
> have a small style guide section in our LDP Author Guide.
> 
> We are discussing the possibility of adopting your guide, in full or
> in part, for ourselves. I assume you won't have any problem with this,
> but I wanted to ask politely anyway. :-)

We have had some discussion of the Gnome Style Guide on the LDP list.
It's a public list, so I'll post a url:

http://list.linuxdoc.org/archive/index.htm?1

I'm not sure how long that will work, but you can get to it via
list.linuxdoc.org if that's dead when you read this. Click the
`discuss' link.

For the authors of the Gnome Style Guide there are some opinions you
may wish to look at. The LDP has traditionally been open to a very
conversational style and most of us consider writing in too formal a
manner to be a disservice. My personal opinion is that the LDP is too
informal, while your suggestions (e.g., no humor, no contractions) are
in a few places too formal.

However, in many ways your document is superior to anything we have,
Still, it remains to be seen exactly what we're going to do with it.
There are portions that are definitely Gnome-specific, there are a few
portions we philosophically disagree with, and we have existing
documentation that is stronger in some ways, better suited to our
processes in some ways, and we do not wish to discard.

Will you advise me on what sort of collaboration you might be
interested in with the LDP? It seems that together we could produce
something better than either one alone, and the problem space is
completely shared between us. Let's work together somehow.

-- 
Dr. David C. Merrill                     http://www.lupercalia.net
Linux Documentation Project                   david lupercalia net
Collection Editor & Coordinator            http://www.linuxdoc.org

The world is not octal despite DEC.