148 lines
5.8 KiB
HTML
148 lines
5.8 KiB
HTML
<!-- MHonArc v2.5.0b2 -->
|
|
<!--X-Subject: RE: Blank template -->
|
|
<!--X-From-R13: Uertbel Zroynap <UZroynapNph-cbegynaq.rqh> -->
|
|
<!--X-Date: Thu, 15 Jun 2000 09:58:32 -0400 (EDT) -->
|
|
<!--X-Message-Id: A5F46F4ED18FD211ABEE00105AC6CF07010937B8@email.cu-portland.edu -->
|
|
<!--X-Content-Type: text/plain -->
|
|
<!--X-Head-End-->
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML//EN">
|
|
<html>
|
|
<head>
|
|
<title>RE: Blank template</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="msg02852.html">Date Prev</a>][<a href="msg02854.html">Date Next</a>][<a href="msg02877.html">Thread Prev</a>][<a href="msg02881.html">Thread Next</a>][<a href="maillist.html#02853">Date Index</a>][<a href="threads.html#02853">Thread Index</a>]
|
|
<!--X-TopPNI-End-->
|
|
<!--X-MsgBody-->
|
|
<!--X-Subject-Header-Begin-->
|
|
<h1>RE: Blank template</h1>
|
|
<hr>
|
|
<!--X-Subject-Header-End-->
|
|
<!--X-Head-of-Message-->
|
|
<ul>
|
|
<li><em>To</em>: <A HREF="mailto:ldp-discuss@lists.linuxdoc.org">ldp-discuss@lists.linuxdoc.org</A></li>
|
|
<li><em>Subject</em>: RE: Blank template</li>
|
|
<li><em>From</em>: Gregory Leblanc <<A HREF="mailto:GLeblanc@cu-portland.edu">GLeblanc@cu-portland.edu</A>></li>
|
|
<li><em>Date</em>: Thu, 15 Jun 2000 06:58:39 -0700</li>
|
|
<li><em>Resent-date</em>: Thu, 15 Jun 2000 09:58:32 -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>: <UDjpU.A.RQD.REOS5@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>
|
|
> -----Original Message-----
|
|
> From: David Merrill [<A HREF="mailto:dcmerrill@mindspring.com">mailto:dcmerrill@mindspring.com</A>]
|
|
> Sent: Thursday, June 15, 2000 4:56 AM
|
|
> To: ldp-discuss@lists.linuxdoc.org
|
|
> Subject: Re: Blank template
|
|
>
|
|
> On Thu, 15 Jun 2000, Chuck Dale wrote:
|
|
> > > > > So, am I going a good direction with this? Too many
|
|
> > > > comments? Too few?
|
|
> > > > > Greg
|
|
> > > >
|
|
> > > > I'm assuming this is aimed at the extreme novice Docbook
|
|
> > > > author; if so, you're
|
|
> > > > right to err on the side of overkill.
|
|
> > >
|
|
> > > ok, I'll stick with lots of comments.
|
|
> >
|
|
> > Ah I'll throw a paddle back in the other direction: way too many
|
|
> > comments. The template needs to be concise to be usable,
|
|
> and some things
|
|
> > are overkill. Like this:
|
|
> [...]
|
|
>
|
|
> I agree with Chuck. I'd rather the template be just that -- a
|
|
> template. No more
|
|
> and no less. With the entire text of DocBook: TDG available
|
|
> online, there's an
|
|
> excellent reference available to everyone, to explain the
|
|
> meaning of any tag.
|
|
|
|
Unfortunately, this isn't necessarily available to everyone. There are
|
|
still a good many people who don't have cheap, high bandwidth internet
|
|
connections. I've had several complaints about my not snipping enough in
|
|
messages lately for just this reason. So, I think I will keep this version
|
|
of the template with many comments, although I may remove some of the more
|
|
pointless ones. But since my comments are comments, marked by <!-- -->,
|
|
they're REALLY easy to strip out. If somebody doesn't already have
|
|
something to do this, I'll write up a script and post it along with the
|
|
template.
|
|
|
|
> I have a bias toward keeping all the documentation together
|
|
> in one document,
|
|
> the LDP-Authoring-HOWTO, instead of spread out between there
|
|
> and comments in
|
|
> the template(s). I see the template as a kind of "Appendix",
|
|
> or supplemental
|
|
> material, to the Authoring-HOWTO. It doesn't need to stand on its own.
|
|
|
|
I'd have to disagree, sort of. I recently became a "new" author for the
|
|
GDP, and found their layout extremely helpful. They have a Handbook for
|
|
writing GNOME documentation, as well as a number of "templates". The
|
|
templates follow the conventions designated out in the handbook, but can
|
|
also be used almost without the handbook. When I began writing
|
|
documentation, I read the handbook, and then grabbed a template, and
|
|
"filled" it in. This gave me a document with structure that was mostly in
|
|
line with the other applications (although a bit different, because it is a
|
|
non-typical application). I think that both are needed, but I think the
|
|
template is a great starting point for new, and returning, authors. The
|
|
ones with comments can be a good way to get started writing as quickly as
|
|
possible, and the completely blank ones can be used by authors who already
|
|
know "everything". Later,
|
|
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-->
|
|
<!--X-References-End-->
|
|
<!--X-BotPNI-->
|
|
<ul>
|
|
<li>Prev by Date:
|
|
<strong><a href="msg02852.html">Re: Blank template</a></strong>
|
|
</li>
|
|
<li>Next by Date:
|
|
<strong><a href="msg02854.html">bootable linux cdrom with root filesystem HOWTO</a></strong>
|
|
</li>
|
|
<li>Previous by thread:
|
|
<strong><a href="msg02877.html">Re: Blank template</a></strong>
|
|
</li>
|
|
<li>Next by thread:
|
|
<strong><a href="msg02881.html">RE: Blank template</a></strong>
|
|
</li>
|
|
<li>Index(es):
|
|
<ul>
|
|
<li><a href="maillist.html#02853"><strong>Date</strong></a></li>
|
|
<li><a href="threads.html#02853"><strong>Thread</strong></a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<!--X-BotPNI-End-->
|
|
<!--X-User-Footer-->
|
|
<!--X-User-Footer-End-->
|
|
</body>
|
|
</html>
|