The installation guide needs improvement

vic

So, it's not a question, but a suggestion, which I don't know where better to make.
The main problem is that install instructions overlap in 2 places (and maybe more):

the INSTALL file (like https://ftp.netbsd.org/pub/NetBSD/NetBSD-9.3/amd64/INSTALL.html )
the part in guide (https://www.netbsd.org/docs/guide/en/part-install.html)

It's very time consuming and error prone to have to read and keep track of both when performing the installation for a first time. Because of that, I actually missed one line in document and distroyed my Windows installation when trying to make dual-boot.

So, the suggestion is to keep installation in a single place - in guide - and keep the other doc just with release-specific things.

Additionally, the guide need re-written; it often it's too verbose and other times too terse. For example, https://www.netbsd.org/docs/guide/en/chap-inst.html#chap-inst-dualboot gives almost no practical info (but takes your time). On the other hand, https://www.netbsd.org/docs/guide/en/chap-inst.html#chap-inst-network-settings doesn't explain exactly how to get those infos. Also https://www.netbsd.org/docs/guide/en/chap-inst.html#chap-inst-bootmedia assumes most users are coming from a Unix-like system?...
Which gives the impression that the entire doc is not being kept up-to-date with the times we live in, or that the audience is mainly people who already are familiar with unix (but then the guide could be made much shorter/less verbose??)

I'm reading now https://docs.freebsd.org/en/books/handbook/bsdinstall/ , and ... compare for yourself.

Vic

nettester

vic Which gives the impression that the entire doc is not being kept up-to-date with the times we live in, or that the audience is mainly people who already are familiar with unix

I am not sure how times play into this as at least Linux (OK, it's not exactly Unix but it's close enough) is actually quite widespread these days. 20 years back there would have been way more people who had never seen anything but DOS/Windows (and maybe a Commodore basic interpreter).

In regards to the target audience: In theory NetBSD is probably not aimed at any specific user group but in reality people installing NetBSD are quite unlikely to be novice users that just felt a bit bored by running Windows all the time. At least i'd be quite surprised otherwise.

netbsdnoob

vic and as a side note, I think we should strive to have man pages at the same level of quality of openbsd.
Unfortunately this is not the case I have to admit.

kc9udx

Are you volunteering your time?

Usually, I wouldn't comment on a thread like this one. Not because, I don't think it's important or unreasonable but, simply because they usually only end-up in pointless discussions.

But, after spending half of my day fixing build fallouts due to a library update. After pushing changes to 4 of those and having fixed 4 more that are still on my local tree and having 4 more to go ...

After build testing 10 other packages to ensure those still build and at the same time keeping my own system up-to-date so, I don't introduce breakage locally ...

After adding support for NetBSD on a few projects allowing them to build, so users can have access to those packages and after being resposible for breaking FreeBSD builds during this process ...

After restoring FreeBSD builds and trying to fix a CI workflow so this won't happen again. A big shout-out to kind soul that helped me out with this, even though he didn't have to.

After all this in one week, sorry to disapoint you but, I just want to relax and don't want to think about documentation.

As said at the start, not because I don't think it's important but, because I've used my time on other things that I believe are as important.

netbsdnoob

pin @pin you could use some help, just ask! 😉

Also, there is a bunch of people that could probably help with docs but we do not know where to report these things and
how to suggest changes.

netbsdnoob yes, here you go: https://www.netbsd.org/docs/guide/en/ap-contrib.html

kc9udx

netbsdnoob which man pages don't you like? NetBSD's man pages are something I've always appreciated. Granted, I've never (successfully) run OpenBSD

netbsdnoob

kc9udx take a look here:
https://www.unitedbsd.com/d/469-netbsd-man-pages/

it was discussed some time ago. For example just check the man for "man" and it does not even mention the man sections,
while openbsd does a much better job at this.

Or the man for a 'ls' compare opensbd and netbsd, or again, chmod where netbsd lacks even practical command execution examples. The list is long, people did a much better job regarding documentation with OpenBSD and FreeBSD .

kc9udx

netbsdnoob well I suppose NetBSD does assume users have a certain level of expertise (which I agree isn't good) but it's also assumed that everyone involved is doing what they can. So if you have ideas about ways you could improve things it might be best to see what you can do about them.

netbsdnoob

pin Thanks but again, we are on the wrong page, we are talking about man pages and the guide refers to the guide itself. So how and where do we send stuff related to man pages?

netbsdnoob See the Contribute Documentation section, https://www.netbsd.org/contrib/#submit-documentation

Thanks!

netbsdnoob

pin Nu pratar vi! Now we are talking my friend!

cornishbeaver

I have only been using NetBSD for three days, and I must say; how much I have loved the experience. OK it's not for newbies, I don't imagine they would be using NetBSD anyway. The installer I have found to be the best, most usable (and I have tried installing this week, OpenBSD, DragonFly and FreeBSD. The NetBSD installer is the easiest, most intuitive and everything worked as I would hope.

Thanks to all developers and contributors. For all you do, so that we can use this fine system.

cornishbeaver don't forget to show us your screen. It's always nice to see what other do with their NetBSD.

kc9udx

cornishbeaver there is one big detail about sysinst that I think is really problematic. But until I run it again, I can't quite put my finger on it.

cornishbeaver

pin I will do that 🙂

cornishbeaver

kc9udx I'll take a look at your video in a minute and subscribe.

GlassNerves

I appreciate the project, but there are areas in the wiki that need updating to align with the current state of the project. This isn't just a critique; I would be enthusiastic about contributing to make those updates.