discuss: LDP Style Guide
Subject:
Re: LDP Style Guide
From:
David Lawyer ####@####.####
Date:
22 Mar 2002 02:47:17 -0000
Message-Id: <20020321174950.B933@lafn.org>
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, ...
I think that most LDP authors are not really developers although many of
them have done some programming or script writing. Developers write
programs and then often document them in man pages, info pages and
manuals that go into the documentation (doc) tree on most Linux
computers. LDP authors generally write integrative documents that
describe how to use a number of programs to accomplish a task. They
seldom are the developers of such programs.
We need to make it easy for prospective authors to publish their work.
Having a long style guide is something that most authors wouldn't want
to use. I like the style guide in the old HOWTO-INDEX. It's just a
paragraph long.
So I don't think that we really need a style guide, at least not a long
one. What I think is more important is to write a very short authoring
guide based on linuxdoc-sgml. I think this guide should contain a
paragraph or two about style. Then we show prospective authors this
simple guide and try to show them how simple it is to become an LDP
author: Use any style you like (provided it's clear what you mean) and
use the simple linuxdoc markup.
If someone is really interested in style guides, there are a number of
them available in libraries. It's been mentioned that there are guides
for both KDE and Gnome and these should be available on the Internet.
What is important is clarity, accuracy, and relevancy. It's not mainly
style (but poor style can result in be unclear presentation).
LDP shouldn't, in my opinion, try to teach people how to write. To
become an LDP author, you are supposed to already know how to write,
along with knowing how to use some kind of an editor or word processor.
A major problem is that some people who are not native speakers of
English tend to use the style of their native language. There's not
much we can do about this except to have people review their work and
help fix it.
David Lawyer
