Nix actually has far better than average documentation compared to other typical open source projects. I started using Nix years ago on Ubuntu to quickly install a package that wasn't present in Ubuntu's repository. Eventually, I began customizing packages using Nix expressions. Before I knew it, I migrated my existing systems over to NixOS. What I can say is it wasn't at all the uphill struggle that's associated with Nix in online discussions. Even though the documentation isn't perfect and going through active improvements, there's a considerable gap between Nix's reputation regarding documentation and my own actual experience.
What surprises me is that people tout RPM/Chef as easier replacements to Nix/NixOS. The assumption about those being "replacements" of each other is questionable because they address different needs. What's even more questionable is the part about RPM or Chef being easy. I have dealt with those two for years as part of my day job, and they're both far from easy. I still have troubles with them to this day. Documentation is far more lacking than Nix, and it's not because things are obvious. If you encounter any trouble, you almost always have to dive into the source code. Navigating the source code of RPM or Chef is a nightmare because the code is scattered across countless different repositories and it's impossible to guess where to look for to begin with. Choice of programming languages doen't help here too. Chef is written in Ruby, which has a tendency of making code ungreppable due to its metaprogramming features. RPM has its own macro syntax which works similar to the C preprocessor. It's very terse and full of gotchas. Navigating around Nix code is much, much easier in comparison. Everything you need is in a single repo, https://github.com/NixOS/nixpkgs, and written in a JSON-like language.
Many people also claim that Nix is hard because it requires a functional programming background. That too doesn't match my experience. Nix expressions are basically JSON with functions. Learning the syntax is a non-issue if you know JSON and some common programming language constructs like conditionals, functions, map, filter and reduce. The only functional programming exposure I had prior to Nix was LISP, in a university classroom. Yet I didn't experience problems learning the syntax. The hard part is learning how to actually utilize the language. The documentation and some grepping around of the Nixpkgs codebase helped a lot with this.