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

[Morten Kjeldgaard <mok@imsb.au.dk>]

On Tue, 11 Jan 2000, Guylhem Aznar wrote:

> Aboloshing the distrinction is a good idea, but it would confuse
> people.

I don't think it would confuse people, but even so, it would only be those
people who are already familiar with the historical distinction. The
overwhelming number of people who _need_ the LDP are newcomers to Linux
that just want to find the information they need quickly.

> mini HOWTOs are "mini" since they focus on a specific topic

Oh? Are you saying HOWTOs don't?  ;-) Kidding aside, I don't think it
matters. HOWTOs, long or short, should go into a subject tree so they are
easy to locate...


On Mon, 10 Jan 2000, David Lawyer wrote:

> HOWTOs and see how they fit into these categories.  I don't think that
> "software/configuration" is a good one for HOWTOs.  Some configuration
> is for hardware yet it's done by software.  Is probing for hardware
> "configuration"?

It was just an example I chose in 0.2 seconds. The subject hierachy should
be worked out very carefully and as David says:

> A HOWTO could belong to various categories.  HOWTOs about hardware
> often cover not only configuring it but much more such as
> troubleshooting it, commands to manually send to it, and even cover
> repairing it.  Installing certain hardware may require special
> cabling, etc.

The key to good documentation is that there are several paths into it. Not
everyone thinks the same. _Organization_ is the key to good documentation,
and the HOWTO/mini-HOWTO distinction is _not_ good organization.


On 10 Jan 2000, Karl EICHWALDER wrote:

> |     <!-- Group: software/configuration -->
> |     <!-- Keywords: sendmail:mail:e-mail:Internet Connectivity: -->
>
> There's no need to misuse comments for this info.  If the linuxdoc or
> the DocBook markup don't fit, extent or customize the DTD: add some more
> elements or attributes.  The way regular XML software will be able to
> work on those documents and to evaluate the info.

I suggested this because it can be implemented TODAY, with LinuxDoc _and_
DocBook. We don't have to wait 3 years for something fancy to evolve. When
such a fancy system is in place, it will be simple to change it, since all
the documents have to be changed anyway. 

My approach can be implemented without forcing anything down peoples
throat. In the example above, someone could write a script to distribute
the information in a directory tree (software/configure) or to generate a
webpage with links, or ...

/Morten

-- 
Morten Kjeldgaard   <mok@imsb.au.dk>             | Phone : +45 89 42 50 26
Institute of Molecular and Structural Biology    | Fax   : +45 86 12 31 78
Aarhus University                                | Home  : +45 86 18 81 80
Gustav Wieds Vej 10 C, DK-8000 Aarhus C, Denmark | icq   : 27224900



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