some beginner feedback

[Tim Howe <timh%dirtymonday.net@localhost>]

Well, I'm not sure you would call me a beginner.  I used NetBSD a little bit
about 8 years ago, but don't remember much.  I do have a fair amount of
experience with OpenBSD and FreeBSD, though.

Specifically I have had trouble with the web site docs and I think some of it
could be fixed just by organizing things a bit better.  The First Steps section
is very disorganized from my perspective of trying to get a newly installed
system working.

The first thing on my mind is configuring the network...

The first steps section starts by talking about possible boot problems or lack
of configuration after install, but I can't help but think this could instead
be a link to an entire troubleshooting section.  It just seemed a distraction
to me.  I understand that it wouldn't to someone who had these problems, but I
think being directed to a problem solving section would be a good step for
those folks.  Maybe even comforting to know that there is this entire section
of fixes waiting for them that has more detail.

The next section about using man is also a good thing to have, but the detail
is a bit much for first steps.  Maybe just suggest afterboot and then link to
another section with more detail.

Then there is a section that suggests learning vi, which is good advice, but I
think saying that at the top of the page instead of making it a section would
be more helpful.

        It also makes no sense to place these two sections before the section
on Login (unless the vi advice is the first thing one sees, but maybe that
should even be before installation if someone is that new).  Speaking of,
shouldn't setting a keyboard type be part of installation?  Anyway...

        I would think that changing the root pass and creating new users could
be saved for "second steps" maybe?  System time and ssh also feel like "second
steps".  The explaination of shadow passwords is very out of place IMO.

        I'm now more than halfway down that page and I haven't seen anything
that I really want to know at this moment...

        Now we get to rc.conf...  I'm told to set rc_configured=YES, which
should have been done already (or should have caused a problem I had to solve
before this point).  Then dhclient=YES, which is assuming a lot; plus I have
not been told how to make it work now without a reboot.  It tells me to define
hostname, but doesn't give the example of what it should look like.  Then it
tells me to set my default route, but wouldn't I have gotten that via DHCP?  If
I am not using DHCP, then why not give info on setting the network up
manually?  How about showing an example of what the finished file should look
like?

        The resolv.conf section makes no mention that the file doesn't exist by
default (again, some explaination about manual vs DHCP config should be made).

        The mounting and installing software should probably be second steps
or, again, links to more detailed sections.

        After all this, I still don't know how to set up my network manually.

        So I went all the way to "Chapter 24. Setting up TCP/IP on NetBSD in
practice".  Wow.  Seeing as how you need to know this stuff to do most other
things, I would think this would be in an earlier section...

        OK, so I find something that tells me /etc/ifconfig.xxx is used for
setting up my network card at boot...  Great!  this is just like OpenBSD then?
I don't see an example anywhere of what goes in this file, though...  And it
isn't until I am in another section halfway down the page that I am told how to
set it up using ifconfig on the command line...

        And then!  I see an example telling me to configure my card in
rc.conf!  Wait what?  So, which is it ifconfig.if or rc.conf?  Or both?

        As it is these docs are not much help.  If I hadn't come from another
BSD I would be lost and frustrated.

        Anyway...  My real reason for going into all this is that I am willing
to help write and organize this documentation if allowed.  Who should I talk
to?  Where do I start?

--TimH