On Wed, Mar 16, 2005 at 09:49:10AM +0100, Hubert Feyrer wrote:
> On Tue, 15 Mar 2005, Bill Squier wrote:
> >This series of "pocket Guides" would fill a large hole in our 
> >documentation.
> 
> Incidentally, there was one posted for NetBSD/sparc today:
> http://www.neuronenwerk.de/files/NetBSD_on_Sparcstation5.pdf
> 
> As you say, first having a few single "pocket Guides" is good. Merging 
> them all into one document -- identifying common and specific parts, etc. 
> -- can be done later. But the information needs to be there first.

I don't like the merging idea if it means the subsequent demise of the pocket
guide.  There's a difference between goals for the sake of goals and goals
that accomplish something.

Nobody wants to be presented with a 50 billion page document that they have
to sift through to determine how to install their Mac Mini.  Especially if
this document ridiculously self-referentially cautions that it SUCKS
(http://tinyurl.com/4kha8).

Again, we are talking about specific install scenarios.  I, and 99% of the
population, are hardly interested in how to set up DHCP and NFS to netboot
their Mac Mini whose hard drive has been subdivided into partitions by one
of the N(!) tools we describe.  The place for this sort of thing _is_ in the
generic guide.

I understand the argument that information will need to be updated in
several places, and I know the danger this is fraught with, but in some
instances, it seems worth the risk.  Perhaps we can mitigate this risk by
sufficiently chunking the docs so that the pocket guides become an
assemblage of small, specific pieces.

I'm talking big, because I'm not going to do most of this work (beyond
providing a beefier Mac Mini how-to in the next week or so).  But for those
of you who are docs people, maybe it's something to think about.

-- 
Bill Squier (groo@netbsd.org)                          http://www.netbsd.org

        I know I don't deserve another chance, but this _is_ America,
        and as an American, aren't I entitled to one?  --Sideshow Bob.