Please stop saying the documentation is "total mess" and "absolute shit" because this is far from the truth. There is comprehensive documentation available for Nix[1] and NixOS[2]. There is an online search for packages [3] and NixOS configuration options [4]. Sure the documentation will be incomplete in places but that doesn't make it "absolute shit", I have found it to be very helpful generally.
Comprehensive is not the same as user friendly, or well paced, or organized in a way that will assist new people learning.
I've seen plenty of projects that were exceptionally well documented. Every method and class had inline docstring documentation, every module has a separate module docstring block. 100% PEP 257 compliance was enforced as part of the CI tool chain... helpful but only after I was sufficiently knowledgeable about the way the project was being used to get any benefit from it. The the sheer volume of documentation meant that many people had written extremely terse explanations, often devoid of any of the contextual information that would significantly improve someone's understanding of how the code in question was be used.
Point is... The volume of documentation or the percentage of documented features, has no direct bearing on its usefulness to any particular user.
I was personally donating monthly to Nix foundation for past few years, the maximum amounts that don't trigger tax concerns, but finally pulled my funding after the team continued to bury their heads in sand about state of docs for newcomers.
The main site docs are incomplete and reference style. The Wiki which had some use cases also had a banner saying it was all deprecated.
So you get newcomers who can't orient themselves, and even advocates like thomastjeffery in this thread who love it but months in still think the docs are wildly unhelpful.
Interestingly, guys who understand it very well are no longer capable of seeing the problem. They forgot what it's like to have no idea how any of it works, so can't describe the happy path between ignorance and the lightbulb coming on -- or even see that path isn't lit.
For now, the only way to walk that path is either absolute focus on learning it w/ no time for a day job, or have your hand held by someone enlightened (which is expensive for your MVPs compared to fixing the docs).
Like I said, after months of using NixOS, I do not understand how to write a simple Nix expression.
Where is this explained?
I am speaking from experience when I say the documentation is "absolute shit". Most of the useful documentation I have read comes from the deprecated wiki.
When I first installed NixOS, I had to read the source code for simple things like defining a user or getting samba set up, and still had to rely on the deprecated outdated wiki.
Three current state of documentation for NixOS is spread between the manual, deprecated wiki, and the source code itself. The manual barely shows how to get a simple system working, but as soon as you reach an edge case - which Nix itself is fantastically suited to handle - you have to start digging.
In time, documentation for NixOS will be mature and usable, but right now it is severely lacking, moreso than any other aspect.
[1] http://nixos.org/nix/manual/
[2] http://nixos.org/nixos/manual/
[3] http://nixos.org/nixos/packages.html
[4] http://nixos.org/nixos/options.html