Re: HOWTO-HOWTO recommendations

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

Big snips ahead...

David Merrill wrote:

[on the template...]
> It will be referenced from the H-H, right?

I hope so but that is up to the author of the H-H. There is a DocBook
version of the Template too so I hope both are referenced.


[on professional inputs...]
> 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?"

This sounds relevant to a style guide. I have made some functional
style comments in the updated Template I announced a few minutes ago.

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

The SGML source contains a lot of indexing, please have a look at
it. I agree it is important in building up a knowledge base and in
letting people seek out the inforamtion quickly. Also the indexing
was used to generate te NetHelp files.

[on organising "Troubleshooting" sections]
> 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.

I believe people turn to the troubleshooting sdections only when
something has gone wrong and that it therefore is handier to keep
in one place. For automatic extraction to a knowledgebase either
way should work as long as the relevant sections are marked up
according to a predefined scheme.

[snip]
> 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".

There is also an "Author/Contribute" box on the LinuxDoc home page
where we could fit in templates (LinuxDoc and DocBook DTD) and
style guides.

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

OK so I messed up the numbering here, it should have been
1-7 consecetively. Personally I see these as documents to
link to from the "Author/Contribute" box. The Template and
the "Link Checking" are available already and might as well
be put up there.

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

The lack of table of contents should have been in the Template but
due to a long standing bug it is missing when using --split=0 to
create a single HTML file.

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

The LDP production should also be availabe on disk, check under
	file:///usr/doc/HOWTO/            (FSSTND)
	file:///usr/share/doc/HOWTO/      (FHS)


Regards,
   Stein Gjoen


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