I switched my personal dotfiles to nix recently, and the “poor documentation “ comment here really hits home.

Trying to learn /how to use/ nix was awful. I found lots of guides, almost always incomplete, and oftentimes directly contradicting each other. It took me weeks to get a working build and much of that time was anything but fun.

I like the outcome, and I’m glad I took the time now, but it was a slog that I don’t think I could really recommend to any of my peers.

It’s too bad guix went full hardcore FOSS and refuses to support macs, because they seem to have better docs and using a language that I can use outside of my package manager makes a lot more sense to me.

40yearoldman

I keep reading, this, and keeping being told this. Yet I switched every system over to nix and have found no thing but the best examples documentation and help from nix to do so.

Within the span of a afternoon and a bit a reading I went from zero, to a script that lets me setup an entire dev systems with just a few commands in a vm, and or even on hardware.

If anything the Nix documentation is just as good as every other thing out there. What is different is there are more than one way to do many things in Nix. This to me I think is the core of complaints. Its a language, and thus the language has may expressions that result in the same outcome.

The second bit I think people struggle with is it is functional. If you look at Nix complaints they appear to nearly be identical to that of Haskell.

soraminazuki

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.