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

[David Lawyer <dave@lafn.org>]

On Tue, Oct 10, 2000 at 11:09:22AM -0700, Gregory Leblanc wrote:
> David, just as strongly as you urge use of LinuxDoc, I urge acceptance of
> DocBook.  I'll make some comments below.

I urge LinuxDoc for some DocBook for others.  If one has a lot of time
to learn, I agree that it's best to go with DocBook.  I just want to
make it clear to each new author that they have a choice.

> 
> > -----Original Message-----
> > From: David Lawyer [mailto:dave@lafn.org]
> > 
> > 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.

We want HOWTOs from people who have a limited amount of time but know
the subject matter well (or are willing to learn) and can write.  Some
people have already written something and have put it on the Internet,
posted it to a newsgroup,  written it for their own use, or have given
a talk on the topic to a Linux User Group, etc.  We need to get these
people to turn it into a HOWTO.  They already know how to proofread,
spellcheck, etc.  But they know next to nothing about using LinuxDoc
or DocBook.

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

Good but a lot of thinking has gone on without using DocBook.  It's a
cost/benefit ratio situation.  For some at a cost of spending 3 times
as long with their doc, they get only say a 3% improvement if they use
DocBook.

> 
> > 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 started on something like this starting with a very simple
example1.sgml LinuxDoc file that only contained 5 tags but is a valid
LinuxDoc doc.  Then example2.sgml introduced several more tags, enough
for one to write a very short HOWTO.  Then more tags were introduced
in example3.sgml but I never finished this.  I'll work on it.  It's
not exactly a template since I don't talk about style.  It's purpose
is to teach LinuxDoc tags (or serve as a reference for them).

Most of the effort learning LinuxDoc is not wasted if one later on
decides to learn DocBook since almost all of the concepts (and tag
meanings) of LinuxDoc are also present in DocBook.

			David Lawyer


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