discuss: LDP Style discussion (cont.)
Subject:
Re: LDP Style discussion (cont.)
From:
David Lawyer ####@####.####
Date:
11 Apr 2002 22:52:23 -0000
Message-Id: <20020411154635.D335@lafn.org>
> On Thur, Mar 21, 2002 at David Lawyer wrote:
> >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. ....
>
On Mon, Apr 08, 2002 at 01:25:37PM -0500, Joy Y Goodreau wrote:
> I totally agree. No long, exhaustive style guide. I will leave the writing
> of the authoring guide in linuxdoc-sgml to you. I know you are the leading
> advocate for linuxdoc.
If the style guide is used by many other projects and is a general style
guide for amateur technical writers on the Internet, then I think it's
worthwhile. Even if it's mainly used by LDP it will be of some benefit.
I was concerned that this project might have a low benefit/effort ratio
if it's only used by LDP. Of course LDP volunteers have the right to
work on any beneficial project which they are enthusiastic about.
As far as an authoring guide with linuxdoc-sgml is concerned, I think
that it would be confusing for the LDP to have two authoring guides.
So the possibilities of using linuxdoc-sgml should be mentioned early on
the the Authoring guide with perhaps a section devoted to it.
> >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.
>
> is incorrect.
I didn't say "write well" :-).
> The whole idea for the style guide and the review of documentation on
> the site came about from working Linux World Expos where multiple
> people would comment on what good information was up on our site, but
> how stale it was and how hard some of it was to read. Granted, not
> all authors will use the style guide, but it will be a reference
> available for those who DO want to write better documentation.
The "stale" problem is worse that the "style" problem. To fix the
"stale" problem means making it easier for authors and recruiting more
of them.
> I can always count on you, David, to be the advocate for making it easy for
> the author. I am hoping that I can be your counter-point as the advocate
> for the reader.
I'm also a 100% advocate for the readers. But if we were to require
perfection from the authors, we would have almost no authors and this
would be a disaster for the readers. So one way to help the readers is
to make it easy for the authors. But not too easy. It's a trade-off
situation because if we had no requirements at all for authors we would
wind up with some really bad documentation with much of it available
in only one format.
David Lawyer
