NixOS installation instructions could use a lot more details

Development
1

First off, I’m posting this not to complain, but to hopefully help improve the experience for other new users.

I’ve used Gentoo and Arch for many years, so perhaps I’ve been spoiled with excellent wikis and docs. After all the good things I’ve heard about NixOS, I’m surprised to see so much missing from the installation docs.

Am I missing some other source, or is this how most users are installing NixOS?
https://nixos.wiki/wiki/Installing_from_Linux

I’m only half way through and already have found a few errors and had to search for other docs. The chroot directory and the new root directory seem to be mixed up in a couple places as well.

Just to pick one example:

# (chroot) NIX_PATH="nixpkgs=channel:nixos-21.11" nixos-install

There’s no explanation for what the NIX_PATH env variable is doing, what kind of channels I should be choosing from, and that I should be updating the version number to the latest release.
There was also no guidance on common things to set in the configuration file. And in the previous paragraph the configuration file to edit was (I believe mistakenly) identified as the liveusb config file, not the newly installed root config file.

If those are indeed the installation instructions that I should be using, would you recommend I just edit them on the wiki as I go with anything that seems like a mistake and add some additional details?

1 Like
2

Oh god no, this is considered an esoteric installation method. The installation section in the nixos manual contains official installation instructions: NixOS 23.11 manual | Nix & NixOS

10 Likes
3

Ahh… thanks, that is indeed a lot better!

3 Likes
4

Do you remember how you ended up on that wiki page rather than on the official install instructions? Might help us increase the visibility of the manual.

6 Likes
5

All the other distros’ official documentation pages are their wikis. You’d look up in the arch or gentoo wiki how to install either.

The mere existence of the installation wiki pages is probably enough to mislead people, just search “nixos wiki install” on $searchengine.

The state of the wiki is probably a problem for beginners in general, there’s so much duplicated (and outdated, or outright wrong) information in there that’s much better represented in the various manuals and nix.dev, but the wiki redirects valuable search queries.

Doesn’t help that the nixpkgs/OS manuals are utterly unreadable/searchable and have poor SEO.

3 Likes
6

Yeah as the other reply suggested, it was a combination of being used to looking at the Arch wiki rather than their official docs, and searching “nixos install guide” on Google returned the wiki first and the official manual second.

2 Likes