Re: HOWTO-HOWTO recommendations

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

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

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.

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

Agreed. Also if you regard it as a check list it might even be of
some use for smaller HOWTOs too.

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

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.


Tangent alert: on looking at the tagged list I feel there is an
extraenous <P> after the definition term. Source:
 <DL>
 <DT><B>Symptoms </B><DD><P>Get <CODE>LI</CODE> and then it hangs.
 <DT><B>Problem</B><DD><P>You use LILO to load Linux but LILO cannot find
your root.
 <DT><B>Solution</B><DD><P>Read the LILO HOWTO.
 </DL>

This leaves the definition term closer to the following definition term
than its own definition term. Moving the <P> to the end of the line
might look better. Comments?


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

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

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.

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

For a more graphic approach one might then try the NetHelp tool, part
of the Netscape browsers. As usual you will find an example on my
home page and also some screenshots in PNG format.

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

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

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

I welcome feedback and hope you and others might find a few things
of interest on my home page.


Regards,
   Stein Gjoen


--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org