There’s https://nix.dev/ which is going in the right direction.
I think nix needs basically something like an extended nix.dev, a one-stop shop for curated, goal-oriented tutorials that cover just enough to understand everything required to achieve some specific goal (i.e. “use flakes”, “override a package version”, “install a non-nix packaged application”), without too much background about how it all works (but links to provide easy looks into documentation and other information sources).
That’ll give a much easier index into the terse inner workings, and with enough reading of something like the above the nix pills lose their complexity.
I’d like to write something like that, but don’t know where to begin, especially since it’d have to be something semi-official that people will easily run into shortly after starting to experiment with nix. And also I don’t know if I actually have the time and writing skills
Basically, I think the “intermediate” documentation for nix is missing. We have great basic beginner docs (the install guide, help menus, error messages, wiki pages, options search and some other things), and lots of heavy docs on nixpkgs and nix (ranging from the nixpkgs documentation all the way to the original nix paper), but not much for slightly more complex use cases that aren’t writing a new distro.
It’s a side effect of the main user being NixOS, and most people huddling around it to make nix work properly. I do think there’s a bit of an ongoing shift, with the growing userbase and the existence of flakes, that may change this though
One small thing that is changing is the new documentation theme for the official docs. Nix 2.4 came with a searchable readthedocsey thing that is much more navigable than the old HTML dump, which has IMO already significantly improved matters. There are upstream issues for doing the same for the nixpkgs and nixos docs.