> It's a language, and thus the language has may expressions that result in the same outcome.
First it's a distribution and a package manager, and the guidance regarding these is sub-par. Especially with what there is of documentation being split between the old and new UIs, then being told about flakes but that they're experimental so it's not clear whether you should or should not use them.
I just went to the nix website, clicked "first steps with nix" and I get https://nixos.org/guides/ad-hoc-developer-environments.html
Is that useful? I'm sure to somebody who already knows what they want out of nix it is, but the first thing I'm told is that shell environments exist and are useful to "use the tool without having to install the software.". Ok, but what if I want to install the software? Then there's listing of what's essentially a magical invocation out of nowhere:
$ nix-shell -p 'python38.withPackages (packages: [ packages.django ])'
I can understand that (or at least reach what I assume is an understanding), but there's no real explanation to give me knowledge to expand upon, if anything the explanations are worse than useless:
> We create an ad hoc environment with $PYTHONPATH set and python available, along with the django package.
thank you very much, that confirms I'd about interpreted the line correctly, but you've not told me what `withPackages` is or where `packages.django` comes out of so I'm not really helped.
And apparently the next step is "declarative and reproducible developer environments", or possibly "towards reproducibility: pinning Nixpkgs"? Or even better, "To quickly setup a Nix project read through Getting started Nix template", I have no clue what a nix project is or why I'd want one.
There's not just a step missing here, there's an entire floor, possibly building. It's like the nix community saw how git is taught and went "we can do worse".