170 lines
6.3 KiB
HTML
170 lines
6.3 KiB
HTML
<!-- MHonArc v2.5.0b2 -->
|
|
<!--X-Subject: Re: HOWTO-HOWTO recommendations -->
|
|
<!--X-From-R13: Egrva Uwbra <ftwbraNznvy.alk.arg> -->
|
|
<!--X-Date: Mon, 5 Jun 2000 08:57:17 -0400 (EDT) -->
|
|
<!--X-Message-Id: 393BA38A.AE39317@mail.nyx.net -->
|
|
<!--X-Content-Type: text/plain -->
|
|
<!--X-Reference: 00060316055702.18200@localhost.localdomain -->
|
|
<!--X-Head-End-->
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML//EN">
|
|
<html>
|
|
<head>
|
|
<title>Re: HOWTO-HOWTO recommendations</title>
|
|
<link rev="made" href="mailto:sgjoen@mail.nyx.net">
|
|
</head>
|
|
<body>
|
|
<!--X-Body-Begin-->
|
|
<!--X-User-Header-->
|
|
<!--X-User-Header-End-->
|
|
<!--X-TopPNI-->
|
|
<hr>
|
|
[<a href="msg02652.html">Date Prev</a>][<a href="msg02654.html">Date Next</a>][<a href="msg02645.html">Thread Prev</a>][<a href="msg02657.html">Thread Next</a>][<a href="maillist.html#02653">Date Index</a>][<a href="threads.html#02653">Thread Index</a>]
|
|
<!--X-TopPNI-End-->
|
|
<!--X-MsgBody-->
|
|
<!--X-Subject-Header-Begin-->
|
|
<h1>Re: HOWTO-HOWTO recommendations</h1>
|
|
<hr>
|
|
<!--X-Subject-Header-End-->
|
|
<!--X-Head-of-Message-->
|
|
<ul>
|
|
<li><em>To</em>: David Merrill <<A HREF="mailto:dcmerrill@mindspring.com">dcmerrill@mindspring.com</A>></li>
|
|
<li><em>Subject</em>: Re: HOWTO-HOWTO recommendations</li>
|
|
<li><em>From</em>: Stein Gjoen <<A HREF="mailto:sgjoen@mail.nyx.net">sgjoen@mail.nyx.net</A>></li>
|
|
<li><em>Date</em>: Mon, 05 Jun 2000 14:56:42 +0200</li>
|
|
<li><em>Cc</em>: <A HREF="mailto:ldp-discuss@lists.debian.org">ldp-discuss@lists.debian.org</A></li>
|
|
<li><em>References</em>: <<a href="msg02645.html">00060316055702.18200@localhost.localdomain</a>></li>
|
|
<li><em>Resent-date</em>: Mon, 5 Jun 2000 08:57:17 -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>: <YOLMAC.A.zUF.tO6O5@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 Merrill wrote:
|
|
>
|
|
> Here are some of my observations after starting to use the HOWTO-HOWTO.
|
|
>
|
|
> I'd like to see a section listing the recommended structure for a HOWTO,
|
|
> something like:
|
|
|
|
[snip]
|
|
|
|
That sounds rather like the Template:
|
|
SGML: <A HREF="http://www.nyx.net/~sgjoen/template.sgml">http://www.nyx.net/~sgjoen/template.sgml</A>
|
|
HTML: <A HREF="http://www.nyx.net/~sgjoen/template.html">http://www.nyx.net/~sgjoen/template.html</A>
|
|
|
|
> I have seen all of these sections in at least one HOWTO, although the terms
|
|
> authors use vary widely. I don't intend for the titles I chose to be cast in
|
|
> stone, just a starting place. The list could also be ordered better.
|
|
|
|
The Template is the skeletal structure behind the Multi Disk HOWTO
|
|
which might be what you are thinking of.
|
|
|
|
> Standardization is a Good Thing, up to a point. Authors
|
|
> should drop any sections that don't apply to them. But, it would be nice if all
|
|
> HOWTOs had similar structures. The HOWTO-HOWTO is the place to codify that.
|
|
|
|
In the update (based on many reader inputs) I'll emphasise it is
|
|
a starting point and not a straightjacket.
|
|
|
|
> Troubleshooting, of course, might be better handled as a subsection within each
|
|
> section, but I think most HOWTOs should have troubleshooting information in one
|
|
> of these two places. This recommendation should go into the text.
|
|
|
|
I believe a dedicated Troubleshooting section withing each HOWTO would
|
|
make it simpler to extract a potential/future LDP-wide troubleshooting
|
|
database, especially as there is no <troubleshoting> tag.
|
|
|
|
> Examples are also very helpful, and we should recommend that authors include
|
|
> them where appropriate.
|
|
|
|
More examples in the Template are coming.
|
|
|
|
> Screenshots and other images can be very helpful in certain topics, and we
|
|
> should recommend their use also.
|
|
|
|
Tricky; also plain ascii should work and is needed by many around
|
|
the world.
|
|
|
|
> We should provide boilerplate for common sections, such as Typographical
|
|
> Conventions and About the LDP, although authors should modify it to meet their
|
|
> individual needs. There are several boilerplates already in the Manifesto. Do
|
|
> they need to be both places?
|
|
|
|
The HOWTO-HOWTO seems to aim for how to work as a HOWTO author
|
|
so I aimed the Template as being just a starting point with some
|
|
examples, partly taking over the old examples.sgml file functions.
|
|
We are missing a style guide but I am hoping to add a little on
|
|
functional style too. It is definitely a missing piece today.
|
|
|
|
[more snip]
|
|
|
|
> I really hope this feedback helps everyone.
|
|
|
|
Feedback is what propels this forward so your comments on the
|
|
Template above would also come in handy. Note that the SGML
|
|
file is teh source and therefore contains a few more embedded
|
|
comments, especially on indexing, something I didn't make
|
|
clear last time I announced it.
|
|
|
|
|
|
Regards,
|
|
Stein Gjoen
|
|
|
|
|
|
--
|
|
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="02657" href="msg02657.html">Re: HOWTO-HOWTO recommendations</a></strong>
|
|
<ul><li><em>From:</em> David Merrill <dcmerrill@mindspring.com></li></ul></li>
|
|
</ul></li></ul>
|
|
<!--X-Follow-Ups-End-->
|
|
<!--X-References-->
|
|
<ul><li><strong>References</strong>:
|
|
<ul>
|
|
<li><strong><a name="02645" href="msg02645.html">HOWTO-HOWTO recommendations</a></strong>
|
|
<ul><li><em>From:</em> David Merrill <dcmerrill@mindspring.com></li></ul></li>
|
|
</ul></li></ul>
|
|
<!--X-References-End-->
|
|
<!--X-BotPNI-->
|
|
<ul>
|
|
<li>Prev by Date:
|
|
<strong><a href="msg02652.html">Re: writing HOWTO in DocBook 3.1 SGML</a></strong>
|
|
</li>
|
|
<li>Next by Date:
|
|
<strong><a href="msg02654.html">Re: HOWTO-HOWTO recommendations</a></strong>
|
|
</li>
|
|
<li>Previous by thread:
|
|
<strong><a href="msg02645.html">HOWTO-HOWTO recommendations</a></strong>
|
|
</li>
|
|
<li>Next by thread:
|
|
<strong><a href="msg02657.html">Re: HOWTO-HOWTO recommendations</a></strong>
|
|
</li>
|
|
<li>Index(es):
|
|
<ul>
|
|
<li><a href="maillist.html#02653"><strong>Date</strong></a></li>
|
|
<li><a href="threads.html#02653"><strong>Thread</strong></a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<!--X-BotPNI-End-->
|
|
<!--X-User-Footer-->
|
|
<!--X-User-Footer-End-->
|
|
</body>
|
|
</html>
|