I used NixOS on three servers for about a year. It was a pain to learn the syntax. It was a pain to read the docs (they're all self-referential and don't explain anything unless you already know how it all works). It was EXCRUCIATING to debug problems (if you screw something up, either it just stops working entirely for no apparent reason, or you get some obscure, seemingly unrelated error deep in the guts of the system). It took 10x as long to add nonstandard software, and maintenance of those packages was a nightmare.
But if you planned to never change anything ever again, it was great (once you got it running) - except when CVEs came out.
Eventually I realized that I didn't actually need immutability. With some carefully maintained shell scripts, a MINIMAL host system, containerization, and a dollop of discipline, I could achieve effectively the same thing on a much more mature system that has a vibrant and helpful community and the long-tail third-party support. Everyone makes a .deb for their software.
NixOS is great and IMHO the lowest maintenance effort of any OS if you can stick to well-packaged software. It's also low effort if you need to package simple things yourself.
However, if you have to use something slightly unusual, it can become very convoluted quite quickly. Sparse documentation doesn't help, as you pointed out. One thing to keep in mind is that there are several escape hatches, such as FHSUserEnv or Distrobox.
But if you need escape hatches too often, it kinda defeats the purpose of using NixOS altogether and something simpler is more adequate.
But if you planned to never change anything ever again, it was great (once you got it running) - except when CVEs came out.
Eventually I realized that I didn't actually need immutability. With some carefully maintained shell scripts, a MINIMAL host system, containerization, and a dollop of discipline, I could achieve effectively the same thing on a much more mature system that has a vibrant and helpful community and the long-tail third-party support. Everyone makes a .deb for their software.
This is how I do it now: https://github.com/kstenerud/proxmox-containers