Re: HOWTO-HOWTO recommendations

[Stein Gjoen <sgjoen@mail.nyx.net>]

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:   http://www.nyx.net/~sgjoen/template.sgml
HTML:   http://www.nyx.net/~sgjoen/template.html

> 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