238 lines
9.4 KiB
HTML
238 lines
9.4 KiB
HTML
<!-- MHonArc v2.5.0b2 -->
|
|
<!--X-Subject: HOWTO-HOWTO recommendations -->
|
|
<!--X-From-R13: Rnivq [reevyy <qpzreevyyNzvaqfcevat.pbz> -->
|
|
<!--X-Date: Sat, 3 Jun 2000 16:14:15 -0400 (EDT) -->
|
|
<!--X-Message-Id: 00060316055702.18200@localhost.localdomain -->
|
|
<!--X-Content-Type: text/plain -->
|
|
<!--X-Head-End-->
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML//EN">
|
|
<html>
|
|
<head>
|
|
<title>HOWTO-HOWTO recommendations</title>
|
|
<link rev="made" href="mailto:dcmerrill@mindspring.com">
|
|
</head>
|
|
<body>
|
|
<!--X-Body-Begin-->
|
|
<!--X-User-Header-->
|
|
<!--X-User-Header-End-->
|
|
<!--X-TopPNI-->
|
|
<hr>
|
|
[<a href="msg02644.html">Date Prev</a>][<a href="msg02646.html">Date Next</a>][<a href="msg02666.html">Thread Prev</a>][<a href="msg02653.html">Thread Next</a>][<a href="maillist.html#02645">Date Index</a>][<a href="threads.html#02645">Thread Index</a>]
|
|
<!--X-TopPNI-End-->
|
|
<!--X-MsgBody-->
|
|
<!--X-Subject-Header-Begin-->
|
|
<h1>HOWTO-HOWTO recommendations</h1>
|
|
<hr>
|
|
<!--X-Subject-Header-End-->
|
|
<!--X-Head-of-Message-->
|
|
<ul>
|
|
<li><em>To</em>: Mark Komarinski <<A HREF="mailto:markk@cgipc.com">markk@cgipc.com</A>>, <A HREF="mailto:ldp-discuss@lists.debian.org">ldp-discuss@lists.debian.org</A></li>
|
|
<li><em>Subject</em>: HOWTO-HOWTO recommendations</li>
|
|
<li><em>From</em>: David Merrill <<A HREF="mailto:dcmerrill@mindspring.com">dcmerrill@mindspring.com</A>></li>
|
|
<li><em>Date</em>: Sat, 3 Jun 2000 02:06:10 -0400</li>
|
|
<li><em>Resent-date</em>: Sat, 3 Jun 2000 16:14:15 -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>: <npnUuD.A.IjB.VcWO5@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>
|
|
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:
|
|
|
|
Table of Contents
|
|
About this HOWTO
|
|
About the LDP (it might be nice to have a little one paragraph blurb at the
|
|
beginning of each HOWTO. See my note above.)
|
|
Purpose / Scope of this Document
|
|
Revision History
|
|
Other Formats of this Document
|
|
Contributors / Acknowledgements
|
|
Feedback and Corrections
|
|
Copyrights and Trademarks
|
|
Terms of Use
|
|
Disclaimer
|
|
Typographical Conventions (Since all LDP documents use, or should use, the
|
|
same conventions, this could be boilerplate. If so, the boilerplate should also
|
|
be in the HOWTO-HOWTO.)
|
|
Requirements
|
|
Introduction (to the subject matter)
|
|
Section 1
|
|
Section 2
|
|
Section 3, etc.
|
|
Frequently Asked Questions
|
|
Troubleshooting
|
|
Appendix 1
|
|
Appendix 2
|
|
Appendix 3, etc.
|
|
Where to Go for More Help (Bad title; you get the idea. This could
|
|
take the form of Bibliography / Suggestions for Further Reading, as well as
|
|
mailing lists, the LUG list at lugwww.counter.li.org and other forms of
|
|
support.)
|
|
Index
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
Examples are also very helpful, and we should recommend that authors include
|
|
them where appropriate.
|
|
|
|
Screenshots and other images can be very helpful in certain topics, and we
|
|
should recommend their use also.
|
|
|
|
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?
|
|
|
|
I noticed that Guy Aznar and Greg Ferguson's "Linux HOWTO Index" contains a
|
|
section called "Writing and Submitting a HOWTO" that is now redundant, and does
|
|
not link to the HOWTO-HOWTO. Perhaps you could get together and decide how to
|
|
work this out. I'd suggest incorporating that section into the HOWTO-HOWTO, and
|
|
replacing it with a short blurb and a link to the HOWTO-HOWTO. You might prefer
|
|
keeping lots of information in the HOWTO Index, but a link should still go to
|
|
the HOWTO-HOWTO, for the details.
|
|
|
|
It must be a difficult job keeping all these various documents up to date,
|
|
especially with so much work going on at the LDP. But people are using it and
|
|
improving it. That means Open Source is working for documentation as well as
|
|
code. Cool.
|
|
|
|
Now some more observations on the structure:
|
|
|
|
In "The Tools", it is not clear what the relationships are between the various
|
|
tools, and how they fit into the overall system. A brief explanation of a
|
|
DocBook environment would be good. Here's a start, or at least an example of
|
|
what I mean:
|
|
|
|
"DocBook for the LDP is a not just a file format; it is an information
|
|
publication system. It is very powerful and flexible; that's why we use it.
|
|
Writing DocBook requires several tools, each of which performs part of the
|
|
overall publishing process.
|
|
|
|
"First, you'll need a text editor or word processor to write the SGML code. If
|
|
you use a text editor, you'll need to write the SGML tags manually. A few more
|
|
featureful word processors will do this for you, although at the expense of
|
|
flexibility. Whether to use a text editor or word processor is up to you.
|
|
|
|
"Once you've written your HOWTO and added the SGML tags, you have an SGML
|
|
source document. You can use [?] to validate your SGML, and find any obvious
|
|
language errors.
|
|
|
|
"After the source document has been validated, it can be "converted" into many
|
|
output formats using various tools.
|
|
|
|
"The conversion tools and a few of the word processors require the DocBook DTD
|
|
and/or DSSSL. The DTD defines the DocBook language, and the DSSSL tells the
|
|
tools how the output should look. If you know HTML, you can think of the DSSSL
|
|
as roughly equivalent to Cascading Style Sheets.
|
|
|
|
"There are additional utilities that can make your life easier. These include
|
|
aspell [any others?]"
|
|
|
|
The whole tools section would be more readable if the tools were divided into
|
|
DTD, DSSSL, Editors, Converters, Utilities, etc. Perhaps this is overkill. At a
|
|
minimum, they should be sorted by tool type, and preferably in installation
|
|
order.
|
|
|
|
Also missing are instructions on what order in which to install the
|
|
tools. It does matter, doesn't it?
|
|
|
|
We could list typical configurations, such as this example I made up, although
|
|
we might want to list known working systems to ensure the examples actually
|
|
work in the real world:
|
|
|
|
DTD: DocBook version 3.1 (this would be kept up to date)
|
|
DSSSL: LDP's customized version
|
|
Editor: LyX, Emacs with PGSML, vi, WordPerfect 9 on Windows, etc.
|
|
Converter: Jade or OpenJade (Is this the right term? Converter?)
|
|
Utilities: sgmltools-lite, TeX (is this a "tool"?), Cygnus DocBook tools
|
|
|
|
All of these items would be hotlinked to the necessary rpm, tarball, etc.
|
|
|
|
"For New Authors" and "Mailing Lists" don't belong under "Getting Started with
|
|
DocBook".
|
|
|
|
At this point, I'm not sure which tools I should install, or in what order. I'm
|
|
stopped until I make that decision. I ordered a copy of "DocBook: The
|
|
Definitive Guide" from Borders. My local store was out of stock, but there is
|
|
one on hold for me on the other side of town. My partner will pick it up Monday.
|
|
|
|
I could plow ahead and make my best guess as to what to do from here, but
|
|
instead I'm going to stop for now. I've given enough feedback for the moment, I
|
|
think, and so I'll proceed after it has been discussed and/or addressed. I'd
|
|
rather see my questions answered in the HOWTO-HOWTO rather than on the list,
|
|
please, if possible, so the answers will benefit others down the road.
|
|
|
|
I really hope this feedback helps everyone.
|
|
|
|
Regards,
|
|
|
|
David
|
|
|
|
--
|
|
David Merrill
|
|
dcmerrill@mindspring.com
|
|
|
|
|
|
--
|
|
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="02653" href="msg02653.html">Re: HOWTO-HOWTO recommendations</a></strong>
|
|
<ul><li><em>From:</em> Stein Gjoen <sgjoen@mail.nyx.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="msg02644.html">Re: Re: writing HOWTO in DocBook 3.1 SGML</a></strong>
|
|
</li>
|
|
<li>Next by Date:
|
|
<strong><a href="msg02646.html">Re: search capability (was: Re: [OT] OpenSource Documentation Fund)</a></strong>
|
|
</li>
|
|
<li>Previous by thread:
|
|
<strong><a href="msg02666.html">Re: writing HOWTO in DocBook 3.1 SGML</a></strong>
|
|
</li>
|
|
<li>Next by thread:
|
|
<strong><a href="msg02653.html">Re: HOWTO-HOWTO recommendations</a></strong>
|
|
</li>
|
|
<li>Index(es):
|
|
<ul>
|
|
<li><a href="maillist.html#02645"><strong>Date</strong></a></li>
|
|
<li><a href="threads.html#02645"><strong>Thread</strong></a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<!--X-BotPNI-End-->
|
|
<!--X-User-Footer-->
|
|
<!--X-User-Footer-End-->
|
|
</body>
|
|
</html>
|