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

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

I'm sending this from a new mail program, so I'll apologize in advance
for anything that looks weird.

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

I can see absolutely no reason to use LinuxDoc. Â If you want to make it
easy, allow plain text. Â If they're going to use markup, have it be
markup that
actually has some meaning.

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

So why even have them learn an inferior and obselete documentation
system 
like LinuxDoc or Yodl? Â Let them submit it in plain text, and we'll get
a volunteer
to turn it into DocBook, and as they maintain and update their document,
they can learn enough SGML to put tags into the document. Â If they use
a real
editor that gives them a list of valid tags, there is almost no effort 
required.

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

Fine, but LinuxDoc isn't going to buy them ANYTHING, no matter how you
look at
it. Â It's just poorly suited for documentation. Â If we get plain text,
at least
we've got something clean to start with to translate it to DocBook.
 With
LinuxDoc, we've got something ugly, with no meaning to the markup, and
which 
has only slowed people down when writing.

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

What's the point? Â LinuxDoc offers little, and I don't believe that
ANBODY
should waste their time learning it anymore.

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

But learning the tags is wasted. Â The concepts can be just as easily
learned 
from DocBook, and if they submit plain text, we can give them DocBook in
return
and perhaps help them with thinking through their documentation writing
as well.

	Greg


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