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.)