Making It Easy For New Authors (was Re: Style Guide)

[David Lawyer <dave@lafn.org>]

On Fri, Oct 06, 2000 at 08:36:06AM -0400, Harvey J. Stein wrote:
> Don't forget that the most important point of the LDP is to get
> documentation.  Any hurdles placed in the way will lead to less
> documentation.  It's one thing to have a Style Guide and another to
> have a Howto Howto with a style section that starts with something
> like "If you're worrying about your writing style, we suggest
> following these guidelines: ...".  Remember - the authors are
> volunteers contributing documentation.  The LDP should make doing that
> as easy as possible.

A major problem is that we are making a huge mistake by not having a
short HOWTO-HOWTO (or the like) that would suggest the use of LinuxDoc
sgml so as to make writing a HOWTO as easy as possible.  The
Contribute/Help document that a prospective author sees first says:
"Potential volunteers should become familiar with the information
contained in the LDP Author Guide".  This is wrong!  The Guide,
although well written, is far too long for many people who want to
quickly write a HOWTO.  It will turn off many potential authors.
Furthermore it doesn't seem to cover LinuxDoc-sgml which is the
simplest format.

I think that this problem needs immediate attention and that a new
author need not understand what a DTD is, what a DSSSL is, etc.  I
wrote a HOWTO without having any idea what these things were.  A new
author that wants to get started quickly should start out with
another HOWTO in LinuxDoc soruce and then just "fill in the blanks".
In other words change the name, date, title, paragraph content etc.

One way to fix this would be to write a short HOWTO-HOWTO and direct
new authors there first.  Then this HOWTO-HOWTO would direct authors
that wanted to understand the situation in more depth to the LDP
Author Guide.  It would also direct them to info on LinuxDoc.  The
existing template for LinuxDoc by Stein Gjoen is too complex and is
titled "HOWTO-template for big HOWTOs".  What about small HOWTOs.
It's not nearly as clear as the example.sgml

I would like to apologize for not saying this earlier.  I did argue
for this previously but not as strongly.  I think by continuing this
we are shooting ourselves in the foot.

Also, the revised Manifesto has a number of problems which I'll
discuss in a later post.

			David Lawyer


--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org