👍️ OK here goes. I started off on https://nixos.org/learn.html, clicked "First steps...", and got to https://nixos.org/guides/ad-hoc-developer-environments.html.

My first bit of feedback on the nix CLI tools is that all of the commands have this long delay that makes me wonder if I installed it right; for example nix-env -qaP git just sits there for tens of seconds, before outputting anything. First time I tried nix I assumed it hanged and went and searched for what I might have done wrong. I would suggest having all the commands print something like "fetching from cache" (maybe only if there's a TTY), and if you want to be fancy do something like a progress bar so that interactive users can see what's going on. This seems small but it's a papercut that every new user is going to hit.

As an aside, I'm already thinking "-qaP ?" I think as a mnemonic/teaching aid, using the full nix-env --query --available -P might help to be clear what's going on. Experienced users can of course use the short form, but the long form is more helpful for explaining to noobs what is actually being done without having to crack open the man page.

The comment "The -I flag pins the Nixpkgs revision to an exact Git revision, leaving no doubt about which exact version of Nix packages will be used." makes my eyes glaze over. How do I get that git revision? Is a user really expected to do this? In practice I don't think I'd use a shell one-liner this way, I'd use a shell.nix, right?

I think this example is bringing in immutability a bit too early, even though it's a defining feature.

The next bit https://nixos.org/guides/towards-reproducibility-pinning-nixpkgs.html#pinning-nixpkgs talks more about this, and feels like the good stuff. But it abandons the python example from before, and so I can't figure out how to use niv.

I want to say something like niv add 'python38.withPackages (packages: [ packages.django ])' to continue building on the previous example of installing Django, but that doesn't work. Even niv add python38 doesn't work.

  FATAL: One or more packages failed to update:
  python38.withPackages (packages: [ packages.django ]): Update failed: Key could not be found: url_template
  CallStack (from HasCallStack):
    error, called at src/Niv/Update.hs:80:25 in niv-0.2.21-K4hQ3qL7WtG6yW48qVS1p3:Niv.Update
ERROR: ExitFailure 1

Not a friendly error message, and I feel like the doc is missing a chance to continue to build on the previous page.

Now that I think of it, python38.withPackages isn't explained in terms of the nix-env -qaP command; teach me how to fish and figure out what package names I should use? nix-env just gives me:

nixpkgs.python        python-2.7.18
nixpkgs.python2       python-2.7.18
nixpkgs.python27Full  python-2.7.18
nixpkgs.python2Full   python-2.7.18
nixpkgs.pythonFull    python-2.7.18

-- where is the python38 coming from? (By which I mean, how does a new user figure out what python3* exist to use?)

One thing the Rust docs (and ecosystem more generally) do is liberally link between different sources of information, so if there is a doc repository hosting the python38 and explaining the withPackages args, linking it so that I can learn about that source of package information would be useful.

Final note -- I feel like this brushes over some core concepts: "You can use the generated nix/sources.nix with a top-level default.nix"

Before you tell me to do a default.nix, maybe explain that and shell.nix and why they are awesome (AIUI these are some of the very cool bits of the nix plumbing).