Re: HOWTO-HOWTO recommendations

[David Merrill <dcmerrill@mindspring.com>]

On Mon, 05 Jun 2000, Stein Gjoen wrote:
> 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 just took a look at the template. You're right, it is very much like the
template, although the template is oriented specifically to large HOWTOs.
Perhaps some of the material you wrote for the template could be used in the
H-H?

Nowhere in the H-H, or in anything else I found on the LDP (please correct me
if it's there but I missed it) was there a reference to the template. Is it a
work in progress?

> > 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.

I hadn't seen the Template before today. Didn't know it existed. Actually,
when I was putting together a skeleton for a HOWTO, I looked at a dozen or so
of the HOWTOs currently at LDP. They don't seem to follow any pattern - it
looks as if each author made up their own structure, at least to some extent.
More likely, they found a HOWTO and copied its structure, but in a modified
form. Then somebody copied their modified form, further modified, etc.

> > 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.

I like that. I came to Linux to get away from straightjackets. :)

> > 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.

I agree with you, that a single troubleshooting section is usually best. But, I
can think of cases where separate troubleshooting sections are best. For
example, larger HOWTOs that cover multiple program installations might be
better if there were a troubleshooting section for each step. This should be at
the author's discretion.

If it would really make a big difference in extracting to a troubleshooting
database, that might make me change my mind on this issue. Tell me how a single
troubleshooting section would make it easier.

> > Examples are also very helpful, and we should recommend that authors include
> > them where appropriate.
> 
> More examples in the Template are coming.

I'm starting to get the feeling everybody else already knows about this
Template and I missed a message somewhere. How is it intended to be used?
Where will it be published? What relationship will it have to the H-H?

> > 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.

Agreed, not all readers will have access to graphics. IMHO, they are really
nice to have when done well, though. Thus, they should always be used as an
additional resource for those who can view them, but the HOWTO should be
accessible and understandable without them. And, if plain text will do the job
just as well, use plain text.

> > 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.

This brings me back to the question of how the template works with the H-H. Is
the template going to be a downloadable file which authors can take, modify,
and flesh out for their own HOWTOs?

If so, is it really a good idea to put the style guide information there,
rather than directly into the H-H? Seems like it belongs more properly in the
H-H to me.

> [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.

Once I actually get my environment working, which I am now sure I will be able
to do, with all the members of this list now having a vested interest in it :),
I will be better able to give you feedback on the template.

-- 
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