Re: HOWTO-HOWTO recommendations

[David Merrill <dcmerrill@mindspring.com>]

On Tue, 06 Jun 2000, Stein Gjoen wrote:
> David Merrill wrote:
> > 
> > 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?
> 
> I agree, in fact in the announcement I wrote
> 	"In the longer term this should probably be part of the
> 	authors guide/resources section."
> and the H-H would be central here.
> 
> > 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?
> 
> Strange. Going back in my logs I see I announced it 8.th May this year
> with a subject line "Announce: template for big HOWTOs". If this didn't
> show up in the search engine on LinuxDoc something must have been wrong.
> I just tried and it works now.

I guess I missed the message, because I lurked on the list starting around
May 1. I didn't try a search specifically for it, because I didn't know it
existed. Sorry.

It will be referenced from the H-H, right?

> > > > 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.
> 
> I am an amateur in this and I feel this is an area where professional
> inputs might be of use and could perhaps be canvassed for in some of
> the other newsgroups, any suggestions on which might be best?

I _am_ a professional. :) I am _not_ a tech writer, but in 20 years of
programming I've done my share. And, I've seen enough, good and bad, to know
what works and what doesn't.

Consider this as an addition to the H-H style guide:

"Write concisely. Organize, organize, organize. Ask yourself these three
questions:

"1. Does every topic contribute to the goal of the document?

"2. Does every subtopic contribute to the goal of the parent topic?

"3. Does every sentence within a subtopic contribute to the goal of
the subtopic?"

I admit to having an organizing/indexing fetish, so if you think I'm too anal,
you can always ignore me. :) Organization seems to be one of the largest
shortcomings of most LDP documentation, although that may reflrect my personal
biases.

> As an aside I have seen some military standards for documentation
> but those were much too complex. The overhead paperage (!) for a
> battleship looked like exceeding the total LDP production which should
> not come as a surprise.

No, that doesn't come as a surprise. My dad was an Army Colonel. :)

[...]
> > > > 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.
> 
> Since we have no tag that describes we have a troubleshooting paragraph
> it would be hard to extract them from a HOWTO. If on the other hand these
> were collected as a list (unnumbered or tagged) in a section always called
> "Troubleshooting", making this an LDP standard, such extraction would be
> simle.

But, if there were multiple sections, always called "Troubleshooting", would it
be any harder? That was what I meant. Either way, you scan for sections named
"Troubleshooting". The difference is that you need a loop; no big deal.

Aside from the technical issue here, I still believe some individual HOWTOs are
better with separate troubleshooting sections, although I also have a strong
preference for a single one in most cases.

> In my attempt of "leading from below" I have an example for you:
> 	http://www.nyx.net/~sgjoen/disk-15.html
> which again is part of the Multi Disk HOWTO, the source of the Template.
> 
[...]
> The Template should have had a homepage line in it which I forgot to
> include. It lives on my home pages at the URLs stated at the top of
> this letter.
> 
> You will find more on my home page
> 	http://www.nyx.net/~sgjoen/home.html

Thanks.

> 
> As a tangent: you and others might then perhaps also have missed
> my announcement of the "Link Checking micro-HOWTO"
> 	http://www.nyx.net/~sgjoen/linkcheck.txt
> which I also had hoped would become part of the authors
> guide/resources section. As usual all comments are welcome.

I'll take  a look at it.

[...]
> > > > 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?
> 
> You and anyone else are welcome to download it any time. Updates to
> the Template will be announced on this list.

IMHO, it should be referenced in the H-H. In fact, each of the author-related
HOWTOs should probably contain a list of all the others -- in the section for
"Further Reading".

> > 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.
> 
> I am not sure myself. The process concists of a number of steps, not all
> are Linux specific. The Template itself could be used to document systems
> based on VAX/VMS if you wish. Here is how I see it:
> 
>  1:get tools and start      H-H        Linux Specific
>  2:intro to SGML            H-H?       General purpose
>  3:intro to LinuxDoc        example/T  Linux specific
>  5:style guide              soon in T  LDP specific, possibly general
>  4:get template and write   Template   General purpose
>  5:submission to LDP        H-H        LDP specific
>  6:link checking            linkcheck  General purpose/HTML
> 
> Hnece it might be argued some modularisation wouldbenefit a
> wider audience, as long as this path is properly described,
> perhaps in the H-H.

In a well-organized HOWTO, the table of contents should, in and of itself, list
the steps.

I like relatively heavy modularisation. But I access all LDP documents online.
In dead tree format, it can be annoying. So, a balance must be struck. The
modularization must sometimes take the form of a section rather than a new
document.

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