by homeworld.cygnus.com with SMTP; 24 Sep 1998 13:28:38 -0000
	by panacea.null.org (8.8.8/8.8.8) with ESMTP id XAA03017;
	Thu, 24 Sep 1998 23:28:16 +1000 (EST)
Message-Id: <199809241328.XAA03017@panacea.null.org>
To: Todd Whitesel <toddpw@best.com>
cc: netbsd-advocacy@NetBSD.ORG
Subject: Re: empirical method for generation of netbsd book. 
In-Reply-To: Message from Todd Whitesel <toddpw@best.com> 
   of "Thu, 24 Sep 1998 01:54:00 MST." <199809240854.BAA01354@shell17.ba.best.com> 
Date: Thu, 24 Sep 1998 23:28:13 +1000
From: Joel Reicher <joel@panacea.null.org>

> I have long held a theory about generating good technical documentation,
...
> It is simply to gather lots of empirical data about what newbie users
> run into while installing and configuring their systems -- what kinds
> of questions they ask, what common problems they encounter, and so on.

FWIW, I agree with this whole-heartedly having been a newbie Not So Long Ago,
and also trying to help other newbies.

> In short, you simply hold a well-stocked installation party and videotape it
> extensively. Make rough transcripts of the various installation efforts and
> use the topics they cover as the raw material for an installation handbook.
...
> However, I think it makes a lot of sense to wait until 1.4-BETA is mostly
> converged before we marshal the resources to actually do this.

Why not start compiling a list of experiences now? Especially since there
are some things that may not crop up in an installation party, such as the
building and using of local shared libraries. Almost every newbie I speak
to hits this and some are told to mess around with ldconfig, some are told
to use LD_LIBRARY_PATH and some use (my preferred method) ld.so.conf.

	- Joel