[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: HOWTO-HOWTO recommendations
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 [email protected]
with a subject of "unsubscribe". Trouble? Contact [email protected]