My problem with documentation isn't so much that the nix language is so hard, but that a nix's package configuration's is (obviously) not the same as upstream.
There's an element of truth to the "poor documentation" complaint, because there are tutorials etc out there that are out of date, incomplete etc. But the official nix project has excellent documentation.
I think the problem is that nix is just hard to learn. It's really different from most package managers, but people expect to look at a few examples and just pick it up intuitively. It's a whole different paradigm, with a custom programming language that also has a different paradigm. (Though Haskell folks eat it right up... no surprise there.)
It's gonna take time and effort to learn it, and there's just no way around it.
Unfortunately, nix is an extremely unfriendly thing in therms of documentation. It almost impossible to graps the meaning of its syntax, although people claim that nix is extremely useful. Nowadays the documentation (or a book) is the only concern that nix's team should be tackling.
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.
What Nix provides in reproducibility and ease of deployment, it certainly makes up for with poor documentation and opaque error messages. I've been trying to learn it for the past few weeks in my spare time for a personal project, and I still struggle with basic things. I love the idea but they really need to invest in better docs, tutorials, and error messages.
Two years ago I tried to set up my home-webserver with nixOS. I failed miserably.
The post hits the nail on the head: The documentation is horrible, and barely differentiates between the language, the package manager and the OS itself.
I really like the idea behind nix; maybe something with better execution comes up one day :)
Nix documentation is such a clusterfuck. You have to basically forage some kind of "most up2date understanding" of basic best practices from random ass blogposts / digging into other people's configs. This is a major red flag.
I think you’re likely right, but as has also been said many time and many ways, the documentation is truly terrible. I don’t know why there isn’t a good documentation set that takes you from nix to nixos to flakes. When do I choose nix shell? Flakes? nix-env? I’ve got a few months between gigs and I’ve been flirty with nix for a year or so so I plan to dig in and master it, but it is mind bogglingly hard to get started.
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.
I am comfortable with writing functional programs, but I have tried and failed multiple times to grok the Nix documentation. The complexity is not because "functional programming is hard", but because the documentation is terrible.
To get me started with Nix, the documentation needs just a few things:
1. Internal consistency: A large fraction of the documentation is spent talking about how great flakes are, with a (last time I checked) big disclaimer at the top saying that flakes are experimental. Another fraction of the documentation talks about how great declarative installations are, while the third happily uses nix-env which, on the surface, seems no different from [apt / dnf] install.
2. How to use the package manager, for dummies. The last time I tried to install NixOS, I tried to install Z3 and its Java bindings, but got completely lost with the "also install the Java bindings" part. I'd rather just spin up a Docker container with my favorite distribution, and put my trusty magic installations there.
3. How to use Nix the language, for dummies. For people wanting to understand the system better than the dummies from part 2. I remember some magic ellipsis, and remaining confused about what they're about.
4. Really what Nix the language is about, for non-dummies.
The documentation currently conflates the last three points, and is internally inconsistent. It is also not clear where users can turn to for help. And then, I install Silverblue on my machine, and for the most part it is rock solid and easy-to-use. Sure, there are some installation commands that I need to run at the beginning of time, but I can put those in a script, and there's my nearly declarative install.
I feel that the criticism regarding documentation is too harsh. Speaking from experience, Nix has more documentation and community resources than most open source projects that I've encountered.
Yeah people say the docs are unapproachable, but I agree the docs are too much "here is how to do a bunch of random things" and not enough systematically describing what Nix is.
>Documentation is just plain AWFUL (as in: complete and technically accurate, but maddeningly obtuse)
Documentation is often just plain erroneous, especially for the new CLI and flakes, not even edge cases. I remember spending some time trying to understand why nix develop doesn't work like described and how to make it work like it should. I feel like nobody ever actually used it for its intended purpose. Turns out that by default it doesn't just drop you into the build-time environment like the docs claim (hermetically sealed with stdenv scripts available), it's not sealed by default and the commandline options have confusing naming, you need to fish out the knowledge from the sources to make it work. Plenty of little things like this.
>In theory, Nix is idempotent and deterministic
I surely wish they talked more about edge cases that break reproducibility. Things like floating point code being sensitive to the order of operations with state potentially leaking from OS preemption, and all that. Which might be obvious, but not saying obvious things explicitly is how you get people shoot themselves in the foot.
This implies that the author of the documentation is the person that wrote the thing though, which is surprisingly rare in larger projects.
I wrote one of the more popular Nix language tutorials[0] and my approach there has been to try and explain everything as straightforwardly as possible and make it work both as a reference and a manual (i.e. you can quickly jump to a section that interests you, or read it from top-to-bottom).
One thing that nixpkgs (the Nix package set, which is ~most of the public Nix code) suffers from is reinvention of abstractions (simply due to its age). For example, most programming languages have their own slightly different implementation of a `withPackages` function that gives you a prepared environment with some dependencies. Some of these use open sets, some of them use closed sets, in the latter cases overlaying things into them can get really confusing even for experienced Nix users and so on.
In my opinion, the community should slow its focus on making lots of new features and spend time consolidating existing logic and agreeing on some basic abstractions. Maintenance work like that is not always fun though, and especially in unpaid open-source projects it's difficult to keep up the motivation for it.
Nix learning curve wouldn't be bad if the documentation wasn't so bad. I have had to put together my configuration based on couple of blogposts from randoms.
If Nix(OS) just had a better documentation ... sigh. Using it feels more like discovering stuff, not utilizing it properly. It's like an adventure, not a tool. Neither is bad, but I think the other way around it would benefit the project.
Plus the nixpkgs and nixos docs are generated from some weird hybrid docbook-markdown that mere mortals (well me at least) can't get to build. So we are stuck using the makes-my-eyes-bleed font on nixos.org, and the gigantic mile-long single-page manual format (which is nice sometimes, like for searching, but other times you want a TOC sidebar).
The documentation for the nix language is all done in mdbook, and is beautiful and easy to read. I wish the nixpkgs/nixos manuals were like that.
I really like Nix so far (just started using it), but damn is the documentation ever shit tier.
reply