Subject: install/14637: Documentation "bugs".
To: None <email@example.com>
From: None <firstname.lastname@example.org>
Date: 11/19/2001 00:19:29
>Synopsis: Documentation "bugs".
>Arrival-Date: Mon Nov 19 00:20:00 PST 2001
>Originator: Rune Kristian Viken
During a discussion on IRC, I claimed that I found OpenBSD's installation-guides and so forth better than NetBSD's, so I was challenged to make some reports about a few things I found a tad 'bad' in the NetBSD installation guide. You may find it irrelevant, but here goes.
Chapter 3. Better explanation of partitioning scheme. Both in the installation-program, and in the manual. Both the partitioning and the disklabelling is a bit confusing for newcomers to netbsd. Especially the confusing use of c: and d: , as it conflicts with 'what you know' from DOS / Windows. Better explanation of how things work BOTH in the installation program, AND in the docs.
Chapter 4.7 is irrelevant for newcomers to NetBSD, as the installer of 1.5.2 takes care of it. Since it is a guide to the newcomers, one can safely assume that they use the latest and greatest release. Covering 'old' details in the installation guide is only confusing. It could be added to an appendix section, a troubleshooting section, a FAQ, or somesuch.
4.8 has some of the same problems.
Chapter 5.5 is hopelessly outdated. You mention that from netbsd 1.4.2 you have .. well, point is, every new user is going to use 1.4.2 or newer, so just cover the useradd comment.
Covering vipw is great in an appendix or in a troubleshooting section, or in a FAQ.
7.4, "pkg_add perl-5.00404.tgz" accomplishes exactly _nothing_ if the user don't know how to get the package in the first place. Its covered in chapter 8, but ..
8.1 - move the "Don't lose the distfiles" part a few section UP, preferrably to _above_ the "rm -rf pkgsrc" command. ;)
Chapter 9. _Great_ explanation of networking for newbies, but shouldn't that be a file outside the _netbsd_ manual? Its informative, but quite irrelevant to the actual problem of installing _netbsd_. Heck, chapter 9 is a _great_ guide for a newbie to set up netbsd in the network at home. But, what about a quick network-setup summary somewhere? :)
Better explanation of how to rebuild the system, similiar to 'make world' under other bsd's. Better explanation of how to configure the compiler to compile for your i686 instead of an i386.
Of course, you may completely disagree with me, and claim that this is not necessarily bad. Its just my opinion, and someone on irc wanted me to subit a bugreport about it. So, here you are. :)