I’ve managed to install NixOS, I’ve installed some programs (are they called packages?) but reading the manual is, a lot of the time, really hard work. For instance, in the ‘best practises’ section it says don’t use with or rec and then a little further on in a different page it gives lots of examples of code which, you’ve guessed it, start with with and rec. Is the manual still a work in progress?
Next, I frequently find code examples, like how to do something in the FAQ: nix.settings = { trusted-substituters = [ "https://cache.nixos.org" ]; substituters = [ "https://cache.nixos.org" ]; };
But there’s no mention of where this goes, some code it seems goes in configuration.nix other code goes in its own file. Please can anyone recommend a coherent and tutorial with explained examples?
The reference manuals are not for reading, but for looking things up. If you’re referring to tutorials and guides nix.dev – yes. Learning has a cost, and Nix requires learning a lot because it does many things differently than what one may be used to, and also not always consistently due to how we arrived at today’s state of affairs.
We, the documentation team, are dedicated to fixing that. Please be patient with us. I expect it to take on the order of years to become a smooth experience. It’s getting better by the day, but until then you can rely on the extraordinarily welcoming community where many people are highly knowledgeable and help out whenever time allows.
Yes. We only recently got to the capacity to make substantial changes, and there is a lot of material to go through. I’d appreciate if you proposed changes with pull requests. There is a good chance they will get merged quickly if they are fairly small, uncontroversial, and follow best practices.
That FAQ was never well maintained. We know it’s a problem, and there is work in progress to clean that up step by step. It will take time though. I expect to see tangible improvement of first-week onboarding by the end of this year. There are lots of details to take care of.
The best you can do to help is put in your time by figuring things out and fixing documentation as you go, or to support the documentation team financially on OpenCollective. We especially need paid maintenance because then we can get work done that volunteers will never take on or finish. This has already allowed us to improve the contribution process, and provided capacity to accommodate work done by volunteers, which would also otherwise linger indefinitely.
I’m collecting general nix/lang/flakes tutorials here and I think there’s a NixOS one in there as well:
I suggested splitting this up into separate sections for nixos, nixlang etc. but that was rejected. I think somebody should do a job of curating good tutorials for nixos.