I think this thread is a great chance for us to reflect on some of the failures of our documentation, esp. when it comes to onboarding new users. Although the nix ecosystem has a lot to offer, it is quickly moving and a lot of different documentation suggests many different approaches to solving the same problem. Nix also has a plethora of different concepts: derivations, the language itself, channels, nix-env, nix-shell, flakes,
nix-foo commands vs
nix foo commands, generations, GC, and so on. It’s kind of a nightmare.
I remember going through the rough patches in the beginning as well, and I still don’t understand everything that nix has to offer. IMHO we ought to rethink what kind of “first impression” experience we want newcomers to have.
For a start I’d like to propose that we
nix-env -i installation with a warning message. Replace it with
nix-shell on https://search.nixos.org/ and all of the documentation.
- Make it dead-simple to install home-manager straight from nixpkgs, no channels funny business. Pointing users towards home-manager straight away will help to alleviate many of the “how do I do X in nix?” issues.
It would also be great to have some kind of semi-official tutorial/video/documentation that walks newcomers through the basic steps of installing and setting up nix, opinionated towards the tools/patterns of the future and avoiding all of the cruft from the past (cough nix-env cough).