HOWTO-HOWTO recommendations

[David Merrill <dcmerrill@mindspring.com>]

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