FRidh: I don't mind sending doc PRs but it's true that one has to agree on the objectives first. I would rather have concise user documentation and (nix/python) developer mode apart (or hidden developer documentation within the same doc).  A user doc could be ten lines: 1/ don't install imperatively
2/ nix-env -if build.nix 
3/ to develop, nix-shell -p dependancies
The reader might not be interested in the details for many reasons,;  when you start with sthg new, you want it to work fast else you give up, because you are compelled to work with nixos thanks to overenthusiast coworkers even though you hate that etc