[arianvanp]

Arch Linux also has a long history of people writing their own package specs (AUR) and is relatively simple too of course.

Let me put it differently. The documentation of NixOS treats package maintainers and users as kind of equal.

This has benefits and downsides. Benefit is that everyone is treated as a power user. Downside is that power users are horrible at writing docs and this philosophy is my main theory why NixOS docs are so .... Bad

Fedora (and RHEL) end user and developer docs are written for quite different audiences

[squiggleblaz]

Yes I just replied to your other comment with the same observation. It reminds me of an article by Paul Graham, I forget which, who expressed the difficulty of explaining to programmers who lack an abstraction just how good the abstraction is. Anything you can do with NixOS, you can do with any distribution, because it isn't magic. But somehow, more stuff becomes possible because it gives you a better way to think.

(As for why the docs are so bad, I think it's because of the lack of good canonical documentation. There's too many copies of it. Search engines ignore the canonical version because it's presented as one giant document. Parts of the system aren't documented at all and you have to work out what you've got by reading the code. The result is that you have no idea what to do if you want to improve the situation - it seems like your best option is to create new documentation. And now you have the same basic level of documentation that didn't help the first hundred times it was rewritten. And I don't really think submitting a PR to nixpkgs is exactly userfriendly, so it probably discourages people from doing the "I'm just trying to understand this, so I'll fix up the documentation as I learn something" thing.)