Don’t get me wrong, maintaining a distribution the way NixOS is a huge effort and I can’t praise the maintainers and developers enough. The ecosystem they’ve built is unlike I’ve seen anywhere, and the technical foundation is sound – in fact I’d wager more sound than what commercial distributions offer. The latter just have more grease. But I do understand the criticism about lacking documentation. But human labor is scarce, and I mean look at me posting this here instead of improving it.
There’s also no good guidance or best practices for packages in nixpkgs and stuff is permanently changing (which in my opinion is good). E.g. did you know that new derivations should be sorted by letters, not categories, and not go into all-packages.nix? At least if your derivation doesn’t require fancy attributes (pardon me if that is not the correct term). Or that stdenv.mkDerivation rec {…} is not best practice, but rather stdenv.mkDerivation (finalAttrs: {…})? And why the latter even works?
Writing good documentation for a system, especially one that’s permanently evolving, is not easy, and I prefer all efforts going to actually maintaining and evolving the system itself than trying to get the perfect documentation that’s outdated in a matter of time. And without trying to gatekeep it, NixOS is a distribution for advanced users. I recommend it to everyone who has a solid understanding of how a Linux system is composed because I think it’s important what NixOS abstracts away from you. And as an advanced user, reading commented code once in a while is fine in my opinion.