@luxus There is this NixOS Wiki page: Comparison of secret managing schemes

Otherwise you're right, and Domen Kožar said the same in his talk yesterday. Converging on recommendations for best practices is something that nix.dev is meant to do, and the Nix documentation team will support all efforts in that direction.

👍️ 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.