by homeworld.cygnus.com with SMTP; 25 Sep 1998 10:21:09 -0000
	by shell17.ba.best.com (8.9.0/8.9.0/best.sh) id DAA08893;
	Fri, 25 Sep 1998 03:19:15 -0700 (PDT)
From: Todd Whitesel <toddpw@best.com>
Message-Id: <199809251019.DAA08893@shell17.ba.best.com>
Subject: Re: empirical method for generation of netbsd book.
In-Reply-To: <XFMail.980924064218.root@garbled.net> from Tim Rightnour at "Sep 24, 98 06:42:18 am"
To: root@garbled.net
Date: Fri, 25 Sep 1998 03:19:15 -0700 (PDT)
Cc: netbsd-advocacy@NetBSD.ORG
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit

(The following gets quite rant-ish -- sorry -- it's meant constructively, but
I got rather frustrated with NetBSD -current practices a couple weeks ago,
and this is a prime opportunity to vent because it is mostly on topic.)

>I think waiting for 1.4 might be a mistake.  As we all know..  releases can
>take awhile, and we never really know when they are coming out.  I think
>writing something now, and updating a few minor nits for 1.4 would deliver
>something alot quicker than starting after 1.4 goes into release cycle.

Ok, perhaps not all the way to beta, but if we start right now, I predict
that right away we will learn:
    - sysinst needs a lot of intelligence to help newbies through weird cases,
	especially common error conditions. An error message that refers you
	to troubleshooting documentation is vastly more useful to a newbie
	than a technically exact error which refers you to the source code.
    - there should be standard scripts for lots of common system admin tasks
	(new user, group, host, net interface, setup web server, file server).
	These could become the basis for a proper sysadmin utility package,
	plus they also become living documentation of what works.
    - our device probing routines could be feeding a lot of hardware info
	directly to X setup and certain package setups (CD's, for example).

I would hate to see a section written that tutorializes the ifconfig man page,
only to see it replaced soon afterward by docs for a script that handles many
common network interface installation situations (including optional use of
network probing techniques such as reverse-arp or DHCP). We should identify
the value of having such a script and coordinate someone to write it.

Once we have automated the most common things that we are used to doing
directly, THEN we let the newbies run wild with it. I should have brought
this up in the first message.

There is also the question of tree structure documentation. I would like to
be able to 'cd' into any directory and run a command to ask for documentation
on what official purpose the files in that directory are supposed to have. If
this command already exists, then it should be on the 'man readme-first' page.
If there is already a 'man readme-first' page, then the initial /etc/motd
after installation should contain the words "Type 'man readme-first' for info
on how to find your way around the system."

Frankly, the NetBSD "solution" is, at this time, still too 'raw' for newbies
who are barely unix-literate to begin with. Especially when they compare us
to FreeBSD or Linux. High visibility right now is actually more harmful to
our "public image" than it would be helpful. I would actually prefer to wait
until we have really Done Right the user conveniences that we currently lack,
so that when we start shining the spotlight on ourselves, we look Really Good.

I have many years of experience with Sun unices, and many months' experience
with nearly every commercial SysV derived machine from the last decade, but
after a week or so of evenings I still do not have my sacrificial i386 box
running -current, because moving from 1.3.2 to -current is so tricky that no
one seems to be able to explain the whole process.

While I may be a minor guru with respect to userland, I feel like a damn
newbie all over again trying to cope with all the undeclared dependencies
in NetBSD development. I want to be contributing changes, not frustrated
that my first major block of free time was pissed away because -current
requires a funky toolchain that does not even run on a stable 1.3.2 system !

I look at the back of the FreeBSD book and I see "recompile the entire
operating system and support software from source with just one command".
Hot DAMN, that's something I can _do_ right away, and if it croaks somewhere
then I can apply typical unix bug hunting procedures to learn what went wrong.

For instance, when I submitted a PR about pkgsrc and xsrc not installing
properly when extracted from root, the response was that it's a feature not
a bug and I should pick a directory for them to go in. No, there should be
a standard directory used by default, and if I want a custom directory then
I can use tar and mv creatively to accomplish whatever I need.

Any time the system requires an input datum before it can proceed, a newbie
question is created that will keep coming back again and again.

I want there to be a standard filesystem location for everything that's needed
to install+build a release system, build a toolchain sufficiently intelligent
to cross-compile -current, sup -current, build -current, and experimentally
reboot into -current. It should be possible to give people cookbook scripts
or commands to do all this, so we have a "reference developer robot" to serve
as a starting point for resolving terminology confusion when discussing things.

>I also think a *really* good place to start would be to look at /usr/share/doc
>and perhaps bring that up to date.  Its a win for the tree even if nothing ever
>gets published.

Maybe this is a faq but is there a friendly on-line reader for those docs?
(Not "?roff with the right options".)

It also would be nice to have new sections in the manual for FAQs and HOWTOs
with index pages ("man faq" and "man howto"). The existence of this structure
would encourage many more people to submit, because there are examples that
they can look at and derive from. It helps divide the process into manageable
chunks that many different people can help out with, further encouraging
actual progress.

In particular, there are zillions of idiotic little things I grumbled about
when getting my first 1.3.2 system set up, and I spent more than enough years
posting on usenet to know how to write up these tidbits in an accessible form.
(See my 'Answer Man #2' column in the first Daemonnews for an example of what
a single long evening and appropriate sacrificial hardware can produce --
plug, plug.)

At first, I just want all those notes to be online in some form accessible by
man or info or whatever, so I can use the pool of accumulated advice on one
system while I am wreaking havoc on another (like a sacrificial machine).
Second, they become raw fodder for people looking to contribute something
small and doable, like a PR that eliminates the problem cleanly. Third, they
are easily appropriated for the book and other docs if they are found to be
Hard Problems.

Todd Whitesel
toddpw @ best.com