167 lines
7.7 KiB
HTML
167 lines
7.7 KiB
HTML
<!-- MHonArc v2.5.0b2 -->
|
|
<!--X-Subject: RE: Making It Easy For New Authors (was Re: Style Guide) -->
|
|
<!--X-From-R13: Uertbel Zroynap <UZroynapNph-cbegynaq.rqh> -->
|
|
<!--X-Date: Tue, 10 Oct 2000 14:07:27 -0400 (EDT) -->
|
|
<!--X-Message-Id: 025836EFF856D411A6660090272811E61D0803@EMAIL -->
|
|
<!--X-Content-Type: text/plain -->
|
|
<!--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="msg03993.html">Date Prev</a>][<a href="msg03995.html">Date Next</a>][<a href="msg03989.html">Thread Prev</a>][<a href="msg03995.html">Thread Next</a>][<a href="maillist.html#03994">Date Index</a>][<a href="threads.html#03994">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>>, <A HREF="mailto:ldp-discuss@lists.debian.org">ldp-discuss@lists.debian.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>: Tue, 10 Oct 2000 11:09:22 -0700</li>
|
|
<li><em>Resent-date</em>: Tue, 10 Oct 2000 14:07:27 -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>: <pjHbbD.A.YyF.ct145@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>
|
|
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 [<A HREF="mailto:dave@lafn.org">mailto:dave@lafn.org</A>]
|
|
>
|
|
> 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
|
|
|
|
</pre>
|
|
|
|
<!--X-Body-of-Message-End-->
|
|
<!--X-MsgBody-End-->
|
|
<!--X-Follow-Ups-->
|
|
<hr>
|
|
<ul><li><strong>Follow-Ups</strong>:
|
|
<ul>
|
|
<li><strong><a name="03995" href="msg03995.html">Re: Making It Easy For New Authors (was Re: Style Guide)</a></strong>
|
|
<ul><li><em>From:</em> hjstein@bfr.co.il (Harvey J. Stein)</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>
|
|
<li><strong><a name="04016" href="msg04016.html">Re: Making It Easy For New Authors (was Re: Style Guide)</a></strong>
|
|
<ul><li><em>From:</em> Hal Burgiss <hburgiss@bellsouth.net></li></ul></li>
|
|
</ul></li></ul>
|
|
<!--X-Follow-Ups-End-->
|
|
<!--X-References-->
|
|
<!--X-References-End-->
|
|
<!--X-BotPNI-->
|
|
<ul>
|
|
<li>Prev by Date:
|
|
<strong><a href="msg03993.html">Re: Making It Easy For New Authors (was Re: Style Guide)</a></strong>
|
|
</li>
|
|
<li>Next by Date:
|
|
<strong><a href="msg03995.html">Re: Making It Easy For New Authors (was Re: Style Guide)</a></strong>
|
|
</li>
|
|
<li>Previous by thread:
|
|
<strong><a href="msg03989.html">RE: Style guide?</a></strong>
|
|
</li>
|
|
<li>Next by thread:
|
|
<strong><a href="msg03995.html">Re: Making It Easy For New Authors (was Re: Style Guide)</a></strong>
|
|
</li>
|
|
<li>Index(es):
|
|
<ul>
|
|
<li><a href="maillist.html#03994"><strong>Date</strong></a></li>
|
|
<li><a href="threads.html#03994"><strong>Thread</strong></a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<!--X-BotPNI-End-->
|
|
<!--X-User-Footer-->
|
|
<!--X-User-Footer-End-->
|
|
</body>
|
|
</html>
|