mini-HOWTO and HOWTO

[Gregory Leblanc <GLeblanc@cu-portland.edu>]

Don't know if you meant this to go to the list, but feel free.  Just give it
a better subject than the old one, since it's a new topic (I've already done
that, and copied the list)

> -----Original Message-----
> From: Peter Hernberg [mailto:petehern@yahoo.com]
> Sent: Thursday, June 01, 2000 6:13 PM
> To: Gregory Leblanc
> Subject: RE: Authorship
> 
> --- Gregory Leblanc <GLeblanc@cu-portland.edu> wrote:
> > I'd like to appologize specifically for some of
> > that.  We've had several
> > long, long, long discussions about merging the minis
> > into the HOWTOs, and it
> > was my understanding that this was "going to
> > happen", but we'd been holding
> > back on doing it for some reason.  Unless somebody
> > objects to merging them,
> > with a good reason behind it, let's say that there
> > aren't any mini-HOWTOs
> > any longer.
> 
> I hate to toss a wrench in the works, but here's my
> two cents: I've also thought of the howtos and the
> mini-howtos as having distinct roles. The roles of the
> mini howtos is to provide a short, quick look a
> narrowly-defined task, while a howto provides a
> broader view of a broader task. For example, the DHCP
> mini HOWTO talks about, well, dhcp, a pretty minor
> piece of networking, while the NET howtwo covers
> networking in general. In practice, the distinction
> may not always be so clear (as some mini-howtos may
> grow and some howtos may never be large or broad in
> the first place), but I think it's still a good
> distinction to make. I don't think it's a bad thing to
> differentiate between task-centric documents and
> topic-centric documents.

I agree with the ideas behind that, although I'd do things a little
differently.
I think that the HOWTO's should any length that they need to get the job
done.  They should be primarily a HOW TO do something, and only get into
background information enough to allow them to make intelligent decisions.  
As an example (I don't mean to pick on anybody, so take this lightly),
Networking related HOWTOs.  Stein's reading guide is kind of a template for
this, although I'd break things into bunches of pieces.  I'd make three
large pieces.  In no particular order, they would be a Networking Guide, a
Networking HOWTO, and a Networking FAQ.  The Guide should contain all kinds
of amazing information about networking, from what a network is, to some
generalizations about writing kernel drivers for network cards.  This
wouldn't be task oriented, but more of something to teach about Networking
in Linux, and some about networking in general.  The HOWTO would be a
process for connecting your Linux computer to a network, and about building
a network of multiple Linux computers so that they can talk to each other.
Not the specific applications (like yp or NFS), but just generally getting
them talking, and confirming that they talk.  The Networking FAQ would cover
the most Frequently Asked questions that come up with regards to Networking,
the Networking Guide, and the Networking HOWTO.  Ideally, we'd have a good
way of linking between these documents.  Hopefully, some of the questions in
the FAQ could be eliminated through clarifications of the HOWTO and Guide,
but not all.
Assuming that we can get a catagorical break down (ala Yahoo!), then you'll
be able to find the NFS HOWTO in the same category as the Networking HOWTO.
And assuming that we can create a decent example multi-author, multi-file
HOWTO, we could even do some aggregation of HOWTOs and Guides, making things
like the Network Server Applications HOWTO possible.  (BTW, that would
probably cover anything that runs as a daemon on your Linux machine and
communicates over the network).  That one might be too broad, but you get
the idea.  Thoughts?
	Greg


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