The nixos.wiki situation is complicated. The community cut ties with the site because the site owner is stubborn
1 Like
Oh I see, that’s unfortunate.
Nevertheless, there is also some duplication between wiki.nixos.org and https://nixos.org/manual/nixos/stable/.
Both address specific package configuration, for which I find the wiki format more appropriate.
As a note, I wouldn’t say that the nix manual or the nixpkgs manual should be in the wiki as languages and frameworks are better described in a manual like it is, in my opinion.
PS: It would be nice if the wiki.nixos.org had a tagging system to link changes to specific nixpkgs revisions. That way one could choose to read the article for the current stable, or unstable.
A lot of people focus on the wiki, but I think the wiki is a poor mans search.nixos.org and I would honestly much rather focus on improving automatically generated documentation from the module system. The modules are what people are interacting with, they already are tagged with the version, they also cannot by definition be stale because they are the interface.
If anything we should want to focus on making writing long form examples directly into the nixos source an easy contribution path and then work on showcasing this data on the nixos.org site.
8 Likes
I would also like to see a better documentation experience, but not in a “we need MORE and BETTER documentation” kind of way. Moreso I’d like to see a reorganization of what information can be found where. I think anytime I’ve wanted to set up some new module or functionality I’m having to jump between three or four tabs to find (in most cases) less than a dozen lines of code and why I need them. This is also barring needing to find forums or random websites for more recent info that isn’t listed in any official site either.
With the official wiki, we now have search.nixos.org, wiki.nixos.org, nixos.org/manual/nixos/unstable, and a few more ancillary sites like nix.dev and the nix and nixpkgs manuals as well that new users are more than likely to come across when trying to find information. (Not to mention the unofficial wiki that refuses to work with us or go away.)
Specifically, I think outlining what information can be found in each location would go a long way. The wiki and the manual are starting to have overlapping entries with different (but mutually needed) information. I’m starting to see wiki pages for options that aren’t in the manual, and manual entries that don’t expand nearly enough on their modules that don’t have wiki pages. Both of these situations force me to manually sort through the options on the options search page, which I’m personally fine with, but trying to figure out what half of those options do are impossible.
Ideally (in my mind at least):
- The wiki serves as a fully enclosed user guide, detailing the steps needed to get a module or item running and listing any bugs/workarounds/noted weird edge cases that are relevant. (A hand-held guide to getting started with individual items.)
- The NixOS manual deals primarily with working in and around NixOS the operating system, not the dozens of modules and services that are optionally enabled/disabled (or at least these are separated into their own category within the manual instead of being randomly lumped in with things like User Management, Display/Window Managers, and Input Methods).
search.nixos.orgexists as it is now, but with better descriptions and maybe a better way to sort by modules. I’d also like to see the ability to somehow embed the relevant options from this into the wiki and the manual, but I’m not sure if that’s feasible or not.
Honestly even if some form of a streamlined documentation guide was made and forcefully displayed for everyone who downloads NixOS, we’d be in a much better position for onboarding new users.
3 Likes
Could nixos.org in the future please please please not recommend installing the nix cli application on Linux by running a shell script downloaded with curl.
It’s very bad practice when it comes to reproducibility and the practical benefits you may like from it. It’s also awful security practice or at least makes that impression. I’ve had friends being immediately turned against nix from reading these download instructions.
Instead, provide advice for downloading from package repos on the most common distros or links to the source to build from. Keep the shell script installer but don’t recommend it for Linux users.
2 Likes
Installation from other linuxes package repositories usually causes more problems than it solves.
Using the official installer or one of the community installers is the way to go.
Feel free to read the script and do the equivalent steps manually.
@nobbz I respectfully disagree, The situation around downstream installers has improved substantially in the past months. Thanks to @imincik we’re running CI tests for various Linux distributions which ensure that application demos on ngi.nixos.org such as for the recently packaged Inventaire work as intended, and the team will be around for following up on breakages for at least another year.
1 Like
This would indeed be a development I appreciate. Thanks for the update.
1 Like
Based on my own brief experience with NixOS so far, I’ve noticed that the “obvious” ways to do things on other Linux distros can be the wrong, “non-canonical” approach on NixOS, and doing things in this wrong way on NixOS can lead to seemingly random breakage and confusion. In my case, I learned that the way interpreters like Python should be used on NixOS is very different from the way that they should be used elsewhere.
I would suggest documentation that steers users away from “bad” practices – especially including practices that work well almost everywhere but NixOS – and towards the practices that would be considered the “Nix way” by NixOS developers. This documentation should preferably be something hard for newbies to ignore, to the extent this is possible.
1 Like