207 lines
9.4 KiB
HTML
207 lines
9.4 KiB
HTML
<!-- MHonArc v2.5.0b2 -->
|
||
<!--X-Subject: Re: Making It Easy For New Authors (was Re: Style Guide) -->
|
||
<!--X-From-R13: Uertbel Zroynap <tyroynapNph-cbegynaq.rqh> -->
|
||
<!--X-Date: Tue, 10 Oct 2000 19:46:12 -0400 (EDT) -->
|
||
<!--X-Message-Id: 200010102348.QAA23819@localhost.localdomain -->
|
||
<!--X-Content-Type: text/plain -->
|
||
<!--X-Reference: 025836EFF856D411A6660090272811E61D0803@EMAIL -->
|
||
<!--X-Reference: 20001010145551.A617@localhost -->
|
||
<!--X-Head-End-->
|
||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML//EN">
|
||
<html>
|
||
<head>
|
||
<title>Re: Making It Easy For New Authors (was Re: Style Guide)</title>
|
||
<link rev="made" href="mailto:gleblanc@cu-portland.edu">
|
||
</head>
|
||
<body>
|
||
<!--X-Body-Begin-->
|
||
<!--X-User-Header-->
|
||
<!--X-User-Header-End-->
|
||
<!--X-TopPNI-->
|
||
<hr>
|
||
[<a href="msg04007.html">Date Prev</a>][<a href="msg04009.html">Date Next</a>][<a href="msg04004.html">Thread Prev</a>][<a href="msg04016.html">Thread Next</a>][<a href="maillist.html#04008">Date Index</a>][<a href="threads.html#04008">Thread Index</a>]
|
||
<!--X-TopPNI-End-->
|
||
<!--X-MsgBody-->
|
||
<!--X-Subject-Header-Begin-->
|
||
<h1>Re: Making It Easy For New Authors (was Re: Style Guide)</h1>
|
||
<hr>
|
||
<!--X-Subject-Header-End-->
|
||
<!--X-Head-of-Message-->
|
||
<ul>
|
||
<li><em>To</em>: David Lawyer <<A HREF="mailto:dave@lafn.org">dave@lafn.org</A>></li>
|
||
<li><em>Subject</em>: Re: Making It Easy For New Authors (was Re: Style Guide)</li>
|
||
<li><em>From</em>: Gregory Leblanc <<A HREF="mailto:gleblanc@cu-portland.edu">gleblanc@cu-portland.edu</A>></li>
|
||
<li><em>Date</em>: 11 Oct 2000 07:48:06 +0800</li>
|
||
<li><em>Cc</em>: <A HREF="mailto:ldp-discuss@lists.linuxdoc.org">ldp-discuss@lists.linuxdoc.org</A></li>
|
||
<li><em>In-reply-to</em>: <<a href="msg04004.html">20001010145551.A617@localhost</a>></li>
|
||
<li><em>References</em>: <<a href="msg03994.html">025836EFF856D411A6660090272811E61D0803@EMAIL</a>> <<a href="msg04004.html">20001010145551.A617@localhost</a>></li>
|
||
<li><em>Resent-date</em>: Tue, 10 Oct 2000 19:46:12 -0400 (EDT)</li>
|
||
<li><em>Resent-from</em>: <A HREF="mailto:ldp-discuss@lists.debian.org">ldp-discuss@lists.debian.org</A></li>
|
||
<li><em>Resent-message-id</em>: <JFWZVC.A.AVC.Br645@murphy></li>
|
||
<li><em>Resent-sender</em>: <A HREF="mailto:ldp-discuss-request@lists.debian.org">ldp-discuss-request@lists.debian.org</A></li>
|
||
</ul>
|
||
<!--X-Head-of-Message-End-->
|
||
<!--X-Head-Body-Sep-Begin-->
|
||
<hr>
|
||
<!--X-Head-Body-Sep-End-->
|
||
<!--X-Body-of-Message-->
|
||
<pre>
|
||
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. <20> If you want to make it
|
||
easy, allow plain text. <20> If they're going to use markup, have it be
|
||
markup that
|
||
actually has some meaning.
|
||
|
||
> > > -----Original Message-----
|
||
> > > From: David Lawyer [<A HREF="mailto:dave@lafn.org">mailto:dave@lafn.org</A>]
|
||
> >
|
||
> > 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? <20> 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. <20> 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. <20> It's just poorly suited for documentation. <20> If we get plain text,
|
||
at least
|
||
we've got something clean to start with to translate it to DocBook.
|
||
<EFBFBD> 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? <20> 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. <20> 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
|
||
|
||
</pre>
|
||
|
||
<!--X-Body-of-Message-End-->
|
||
<!--X-MsgBody-End-->
|
||
<!--X-Follow-Ups-->
|
||
<hr>
|
||
<!--X-Follow-Ups-End-->
|
||
<!--X-References-->
|
||
<ul><li><strong>References</strong>:
|
||
<ul>
|
||
<li><strong><a name="03994" href="msg03994.html">RE: Making It Easy For New Authors (was Re: Style Guide)</a></strong>
|
||
<ul><li><em>From:</em> Gregory Leblanc <GLeblanc@cu-portland.edu></li></ul></li>
|
||
<li><strong><a name="04004" href="msg04004.html">Re: Making It Easy For New Authors (was Re: Style Guide)</a></strong>
|
||
<ul><li><em>From:</em> David Lawyer <dave@lafn.org></li></ul></li>
|
||
</ul></li></ul>
|
||
<!--X-References-End-->
|
||
<!--X-BotPNI-->
|
||
<ul>
|
||
<li>Prev by Date:
|
||
<strong><a href="msg04007.html">Re: Making It Easy For New Authors (was Re: Style Guide)</a></strong>
|
||
</li>
|
||
<li>Next by Date:
|
||
<strong><a href="msg04009.html">Re: I'm a sucker</a></strong>
|
||
</li>
|
||
<li>Previous by thread:
|
||
<strong><a href="msg04004.html">Re: Making It Easy For New Authors (was Re: Style Guide)</a></strong>
|
||
</li>
|
||
<li>Next by thread:
|
||
<strong><a href="msg04016.html">Re: Making It Easy For New Authors (was Re: Style Guide)</a></strong>
|
||
</li>
|
||
<li>Index(es):
|
||
<ul>
|
||
<li><a href="maillist.html#04008"><strong>Date</strong></a></li>
|
||
<li><a href="threads.html#04008"><strong>Thread</strong></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<!--X-BotPNI-End-->
|
||
<!--X-User-Footer-->
|
||
<!--X-User-Footer-End-->
|
||
</body>
|
||
</html>
|