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

[Gregory Leblanc <GLeblanc@cu-portland.edu>]

David, just as strongly as you urge use of LinuxDoc, I urge acceptance of
DocBook.  I'll make some comments below.

> -----Original Message-----
> From: David Lawyer [mailto: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 don't think we want HOWTOs by people who aren't willing to take some time
and actually write something decent.  If they want to quickly write a HOWTO,
chances are that they won't have time to keep it updated, or to ensure it's
technical accuracy, or to proofread and spell check it.

> 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 find LinuxDoc harder to write than DocBook.  With DocBook, I can remind
myself that this is a filename, this is a directory, this one is an
application, and that one is a program listing.  Yes, it's more complex, but
it makes me THINK about what I'm writing, and figure out exactly what I'm
saying.  Even if we didn't render any of the tags, and only provided plain
text, I'd still write in DocBook, as it helps me think.

> 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 agree that the templates are too much for simpler HOWTOs, but we could
certainly create templates for basic HOWTOs, it just hasn't gotten done.  If
somebody went and created them, I'm sure it would be easy to make them
available.

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

I think that by encouraging people to use LinuxDoc, we're shooting THEM in
the foot.  Writing documentation isn't easy, and it never will be.  To
write, you must have a good command of language, as well as a good command
of the topic that you're writing of.  DocBook helps to expose and encourage
good technical writing.  LinuxDoc lets you translate into many different
output formats, and nothing more.  I couldn't use LinuxDoc to help me
include technical details if I wanted to.
	Greg


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