Re: HOWTO vs mini-HOWTO [was: Linux Doc Infrastructure]

["der.hans" <ldp-discuss@LuftHans.com>]

On Wed, 12 Jan 2000, Kim Lester wrote:

> "der.hans" wrote:
> > 
> > 
> > Many of the minis need to be incorporated into the regular howtos or
> > merged together with like topics anyway. For instance, I plan on making a
> > "removable drive HOWTO" as soon as I get my scsi card working with my
> > laptop. This will include stuff from all the Zip and Jaz (mini-)HOWTO,
> > which I believe haven't been updated in eons. The same info applies for
> > Zip, Jaz, Orb, so it should all be in one place having to do with the
> > overall topic.
> > 
>   The HOWTO structure certainly needs an overhaul.
>   I'd suggest that it would be better if each topic be kept separate
>   (eg Jaz topic, Zip topic etc along with a parent topic on "Removable
> Drives"
>   and that these all be linked together into a "virtual" document
> (rather than
>   one physically large one).

This is really somewhat how I see it, except I think it should be a single
document with chapters that are available for export, if necessary.

These drives are mostly all the same. Why should we have different docs
for them? It's free sponsorship for the products. There aren't HOWTOs for
each tape vendor and going from one type of tape media to another is much,
much more a pain than working with different removable drives :).

>   The benefits include ease of maintenace. Eg Zip brought out a Zip250.
> It would
>   be better to just edit a small Zip document (that several other
> virtual docs may
>   refer to) than to edit a monolithic doc - (which would accumulate many
> updates).

This seems to more of the card catalog thing over at metalab.

Having a good index will fix many of the problems with finding data. The
examples about trying to find something in the index in the back of a book
were excellent. Well, since we're working on a an electronic medium we can
reference the same doc or same sub-section of a doc from as many keywords
as we feel appropriate. Put ppp under ppp, dialup, networking, serial
communications, connecting to an isp, etc.

>   To belabour my point further :-)
>   Suppose  a company TopHat makes a distribution and wants to add
>   notes about removable drive issues under their distribution. They
> could
>   just add a section (like a node in texInfo) and still reference your
>    great, up-to-date, docs without having to either a) rewrite it or b)
>    referring a user a set of misc. other files to look at.

I'd say they can make changes for the copies to go out with their dist and
should submit those changes to the doc maintainer if they want them
included in the ldp. By having one doc, they don't have to cover each of
the drives.

If that doc ends up being virtual and getting specific parts such as zip
info, orb info, etc. at build time or is one doc that exports those as
chapters doesn't matter so much, but I really think the latter is
better. That isn't necessarily the case for all similar circumstances. I
don't know if we want to have one method for dealing with these types of
issues or decide it in a case by case manner. All things are black and
white, except those that aren't :).

ciao,

der.hans

>  regards
> 
> 	Kim

-- 
# +++++++++++=================================+++++++++++ #
#                 der.hans@LuftHans.com                   #
#            http://home.pages.de/~lufthans/              #
#   I'm not anti-social, I'm pro-individual. - der.hans   #
# ===========+++++++++++++++++++++++++++++++++=========== #


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