To quote Andy Warhol, "They always say that time changes things, but you actually have to change them yourself."
I don't mean you personally! I mean that it's not clear how time is going to fix Nix's documentation.
My guess is that at some point a big company will either clone or copy NixOS and enforce some discipline on the documentation. At that point it'll take over the world.
This is my estimate based on the work that has happened over the last two years. There is steady movement in the right direction and the community is organized alongside the NixOS Foundation members to make things happen. Just not at a break-neck pace. Places like Determinate Systems, Tweag, etc are the largest forces currently, but there are plenty of others that are trying to move things along. Over time, that steady movement will land Nix in a place where its pains have been largely dealt with. I don't think we're there yet and, at this pace, won't be for a while.