Let’s face it, NixOS documentation is a mess.
Looking at other distributions with steep learning curves, such as Gentoo or Arch, documentation is trivial. Arch, in particular, has done a fantastic job of providing clear and concise documentation. So much so that, in fact, users of other distros often look at the Arch wiki to find information they need. The Gentoo wiki, although less popular, is also highly detailed.
NixOS, with its even steeper learning curve, of course needs documentation that is as thorough, useful, and extensive as that of its fellow “advanced” distros. The fact that it doesn’t, therefore, makes learning it borderline Herculean for any unsuspecting user hoping to try it out.
The official wiki is flawed. Although wikis are a popular format for cataloging a lot of information on one website, the NixOS wiki allows anyone to contribute. We find this model to only function effectively for a platform like Wikipedia that has a shockingly large editor-base. For one of the most niche operating systems on the planet, a wiki that relies on crowdsourcing is doomed to inaccuracies, shallow information, and generally, less effective development.
Alternatively, of course, NixOS has a manual. The manual is great. Information is updated quickly and a pull request, approved by the NixOS documentation team, is an effective method of change.
However, the manual is not without issues. It does not cover “experimental” features in the Nix ecosystem, such as the widely used Flakes or the accompanying CLI. As such, it could never be a properly extensive document. Furthermore, its single-page structure makes reading it a chore, and it is quite difficult for new users to read and understand its contents.
Plenty of third party documentation also exists, however they may be outdated or difficult to read for a new user.
Although we at the unnamed NUG realize we run the risk of letting standards proliferate, we feel that we have the ability and the will to make NixOS documentation that is user friendly, comfortable to read, and covers all areas of NixOS users may wish to learn.
Therefore, we are proud to introduce you to our official manual, Sherpa.
Named after the Sherpa people of Nepal, who are known for their mountaineering skills and as mountain guides, the Sherpa manual is your guide to navigating the world of NixOS.
Our design goal for Sherpa is simple: a new user with zero knowledge on coding and/or Nix should be able to read and understand it enough to use NixOS effectively. Although we can’t guarantee this goal is decisively met, we continuously strive to further improve and develop the state of documentation in NixOS.
Welcome to NixOS; we wish you luck on your journey up the mountain.