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

[Mark Komarinski <markk@cgipc.com>]

David Lawyer wrote:
> 
> 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 disagree on a number of points.

I won't get into the LinuxDoc/DocBook thing.  We already went through that
war.
The LAG is as long as it is because it goes through so much.  Which is why
it's now classified as a guide instead of a HOWTO.  The style guides
and templates will help any author quickly get started.
I'm also starting to make it my personal mission to start showing people
how to write LDP documentation.  I'm already set to show this in Toronto at
the end of the month, and in Paris in January.  With any luck, I'll be
in a position by then when I can attend more conventions and get more
information out.  Probably attend random LUG meetings in New England and
spread the word some more.  Anyone who wants to assist in this effort can drop
me an e-mail.  Maybe I'll make a general-purpose StarPresent presentation
that can be given.
 
> 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.

I think we're now crossing the line between "someone who wants to write
a document" and "an LDP author who wants to maintain a document".  Just
plain writing a document and sending it to the LDP isn't enough (unfortunately).
The author will need to know how to validate, how to install the DTD/jade,
how to view the resulting output, and how to use CVS.  This ain't easy, and
the LAG covers all those points.

> 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.

Using outdated DTDs will shoot ourselves in the foot.  We need
to get with the times and use some recent (and better documented) DTDs.
 
-Mark


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