Subject:
Re: LDP Style Guide
From:
"Tabatha Persad" ####@####.####
Date:
20 Mar 2002 09:31:23 -0000
Message-Id: <002701c1cf28$ed3d17d0$0928a8c0@voodoochild>
I have taken some time in the recent past to read the Gnome Style Guide. It
is exhaustive. Ok, er, comprehensive.
Perhaps I'll go back and take another look and find some of the key
components that do comprise at least the fundamentals - organization of
material in a logical approach, and explanation of technical material in
relation to the target audience.
One thing that they seem to be big on in the GDP is the grammar of the
documents, for translation purposes. Some things don't translate very well
from English to other languages, such as contractions (don't, you're, it's),
which they discourage for that reason. Point of view, in the case of
writing TO the reader, makes it easier for the audience to relate to. GDP
also discourages a lot of slang and anything that may be unclear. They go
on to suggest pages of do's and don'ts in this regard.
I think, personally, one of the best ways an author can let their
personality out is to write a small introduction or foreword, and then
proceed with writing the rest of the documentation in a friendly but
appropriately articulate manner. The reader will already have an idea of
what the author's personality is like without having it constantly injected
throughout the documentation, which (and I speak from experience) could
interfere with following given instructions.
Some thoughts.
Let me know if I can help sketch out a TOC.
Thanks!
Tabatha
----- Original Message -----
From: "Joy Y Goodreau" ####@####.####
To: "David Merrill" ####@####.####
Cc: ####@####.####
Sent: Tuesday, March 19, 2002 1:28 PM
Subject: Re: LDP Style Guide
>
> I'm sorry but I am going to have to disagree with you. The GNOME Style
> Guide definitely serves its purpose inside the GNOME project, but it is
not
> a Style Guide for developers. It is very much like traditional style
> guides. Simply referencing a style guide in order to have one is not the
> ideal here. We need a usable style guide that helps our authors write by
> addressing their needs in their terms. I do not think that we want the
> level of control that the guide represents. If a document like a style
> guide is hard to use, writers simply don't use it. What happens then is
> that it becomes the editors and reviewers job to enforce all the rules
that
> the developers did not understand.
>
> If there is a large out cry from writers that have looked at the GNOME
> Style Guide and are ready to write by it and have the reviewers stick to
it
> for our publication policies, then please let me know. I will stand
> corrected. I just think it will create a lot more work for the editors,
and
> I don't think that the majority of the writers will use it.
>
> thanks,
>
> joy
>
>
> Joy Yokley Goodreau
> Linux Information Development
> IBM Linux Technology Services
> 512-838-4118
> ####@####.####
>
>
>
>
> David Merrill
> <david@lupercalia To:
####@####.####
> .net> cc:
> Subject: Re: LDP Style
Guide
> 03/19/02 03:44 PM
>
>
>
>
>
>
> On Tue, Mar 19, 2002 at 12:29:04PM -0600, Joy Y Goodreau wrote:
> > I am interested in putting together a style guide for the LDP to guide
> > reviewers and authors in publishing and maintaining high quality
> > documentation. Unlike other Style Guide projects in existence, this
would
> > be tailored towards developers, not toward individuals who already know
> > what "gerund phrases" and "dangling participles" are. In fact, this
Guide
> > will try a new approach to style by providing an easy-to-use reference
> for
> > style that includes, instead of excluding, would be writers.
>
> I spoke to the Gnome people about using the Gnome Style Guide, or
> adapting it, or something. They were agreeable; I ran out of time and
> never did anything with it. It is very good, but a bit Gnome-specific.
> You'll find it on the GDP page. It might be helpful.
>
> --
> David C. Merrill http://www.lupercalia.net
> Linux Documentation Project ####@####.####
> Lead Developer http://www.linuxdoc.org
>
> It's fair to say that the Internet promise has become the newest market in
> our economy, and access should not be controlled by any one company.
> Microsoft currently enjoys a monopoly that controls more than 90 percent
of
> the desktop computer today.
> --Retired US Senator & former presidential candidate Robert Dole
>
> _________________________
> http://list.linuxdoc.org/
>
>
>
>
>
> _________________________
> http://list.linuxdoc.org/
>
