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

[David Lloyd <lloy0076@rebel.net.au>]

David et al:

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

Or DocBook...with a reference perhaps to http://www.docbook.org/

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

"For a brief introduction to the LDP, please read the LDP-Howto...for an
in-depth guide please read the LDP Author Guide". It sounds like a good
idea.

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

That's the perennial problem of all documentation. The man pages are
much more terse but people don't read them :-)

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

Hang on. You could do the same with DocBook XML or 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.

By continuing what? This subject?

DL
-- 
And so it was that later
As the miller told his tale
That a face that at first was ghostly
Turned a whiter shade of pale....


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