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 don't understand what's wrong with the Nix language. Sure, the space-delimited lists can get a little annoying, but other than that it's minimalistic enough to use a configuration language but complex enough to do more complicated things like overriding derivations. Maybe it's because I learnt Haskell before Nix so the syntax is very familiar to me, whereas I see how it could be a learning curve for other users.
What I find the most annoying is the lack of documentation of some of the nixpkgs functions. Some of the functions provided by import <nixpkgs> {}.lib appear to be the same as the ones builtin to the Nix language and there doesn't seem to be any clear guidance on when to use which version. I've also had to look at the source code to find out the difference between writeTextFile, writeText, writeTextDir, writeScript, and writeScriptBin. [The docs][1] explain writeTextFile, but the only documentation for the rest is ‘Many more commands wrap writeTextFile including writeText, writeTextDir, writeScript, and writeScriptBin. These are convenience functions over writeTextFile.’.
Additionally, it's a bit frustrating for me how all the documentation for nixpkgs — the lib functions, how to make a derivation, specific details for building packages in certain languages, how to contribute to nixpkgs, overriding packages/overlays etc — are in [one gigantic web page][2] that's quite slow to load and even slower to search for things in.
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.
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 :)
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.
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.
As someone just getting started with Nix & NixOS, I couldn't agree more.
In terms of documentation: the lines between nix-the-language, nix-the-tool, and nixos-the-system are often too blurry. Familiarity with one of the three is often assumed or implied.
Everyone seems to be using Flakes and/or home-manager; the official docs and tools all try to scare you away by labeling it unstable/experimental (if ever mentioning them at all), yet it seems difficult to find third-party resources that don't refer you to Flakes at some point.
The "getting started" manual is very good at getting you to a basic and very usable desktop system, but once you want to go anywhere beyond that, the difficulty (and complexity) immediately ramps up to crazy levels.
The references usually feel like they're complete, but I found it extremely difficult to find a simple answer to quite basic questions of the "how to do X" kind; e.g. I want to supply the same list of packages to python310.withPackages and python311.withPackages, to have both Python versions available system-wide (so I can trivially fire up an IPython shell and hack away at a simple problem). I solved this on other systems e.g. by using stupid text substitutions in a shell script, or calling "python3.xx -m pip -r requirements.txt", but it's still unclear to me how to do it with Nix - do I need to learn more of the language, or more about nixpkgs, do I stick with copy-pasting the package list, etc.
I wish the documentation was even 10% as good as OpenBSD's, but many commands don't even have basic man pages. It's definitely the most intriguing OS I've tried in many years, with a lot of promise for a return on the investment, it's just that it feels incredibly steep to get anywhere when you're just getting started.
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.
All these wrappers are there because nixpkgs doesn't have non-awkward ways to deal with the stuff people deal with often. Nix the language is probably the least of the issues, it's maybe a few % of the chaotic Nix ecosystem. Most of the logic (that desperately needs proper documentation) is in nixpkgs and tooling.
> The problem is, documentation is sparse to non-existant, error messages are poor and often far from the actual problem, and it makes use of concept that lots of people are not familiar with (like lazy evaluation) without ever explaining them, resulting in surprising semantics.
Absolutely, that is the major roadblock for Nix/OS in my opinion, with the new `nix` command, the documentation is way better but the language and OS documentation is still bad, if you search for something on a search engine, the top result will probably be the NixOS Wiki which is not even official! Manuals can come up but the title for the nix manual (not NixOS) is "NixOS - Nix 2.3.15 Manual" which is confusing by itself but even more so when you're trying to solve a specific problem and not just get the manual. Having the "NixOS" part at the end for example would already help. Having titles for different parts of the manuals would be best. However, manuals are single pages except for the new nix command manual.
That is a truly horrible user experience in my opinion...
NixOS is however very good in other areas so the experience is positive in general but if resolution of issues could be faster, it would help significantly. My guess is that they will push towards the new manual format, so this will get resolved eventually but it will probably take a long time.
They are also probably not aware of certain issues like the fact that having no roadmap is not great for end users or contributors and doesn't create this focused effort that is required to solve the issues mentioned. Nix devs seem to be a bit too technical which is becoming a problem. If you guix to nix, they are much more organized, if you go to their homepage and want to contribute, it is very clear where you can contribute and how.
Another example would be flakes. They created quite a hard split in the community between people that are using them and people that are not. They have some problems sure, but I think they should become standard and then be iterated upon.
To summarize, the Nix/OS project feels to me like it is still treated like a research project with no users and few contributors which is not the case.
I really like the idea of NixOS, but there not being a single clear guide of how to set everything up (and the messy documentation) is the biggest thing holding me back. I also really don't like wasting so much time on tinkering with my system the way I used to do.
But I'm seeing so much Nix news these past few weeks, I guess it'll be better in a few years!
> My real gripe with Nix is the lack of a complete, easy to find, documentation of its "standard library". Nix Pills & a few wiki pages are far from enough.
How hard have you tried? It's literally two clicks and one scroll away from the official home page: https://nixos.org/ -> click "Learn" -> Scroll down -> click "Full Nix Manual":
The Guix actually docs look like the current Nix docs, which I presume is not a coincidence given the nature of Guix. These are not bad docs by any means, but the Arch wiki is a wealth of documentation that goes far beyond the norms, documenting all sorts of things that are not part of the base system, including quirks with specific hardware and software. There's nothing wrong with the docs Nix and Guix have today, they're just not really the same thing as Arch Wiki. NixOS has an unofficial wiki, which is a bit more apples-to-apples, but it's relatively bare for now.
That having been said, I think I'd have a bit of trouble adopting the Guix system though, because I rely pretty heavily on the NixOS options search, and it seems Guix at this moment only has a package search.
My very personal main pain point is documentation: Nix/NixOS do have some, but mostly or too little or deprecated.
Where is a proper Flake documentation? Where is a proper $newNixFeatureInVogueNow?
The second pain point is: Nix might sound nice to read and write as a language for Haskellers, but most people actually aren't haskellers...
The third is essentially the fists, more specified: target. If the target is desktop, or server, or HPC, or development docs should be shaped per target. Actually NixOS is designed mostly with dev desktops and infra target, but docs are not even for new devs, more something added aside just because it's part of the duty provide them in some form...
I am of a similar opinion, but I think it's largely due to my typical use case.
If you use Nix in a "drive-by" kind of way, it's very hard to make any inroads into the language. The documentation and tutorials are not really intended for a casual user - it is expected you will sit down with the Nix site like a good book, and go at it from start to finish. If (like me) you instead touch Nix little and often, doing small invocations or on-the-fly editing, the docs are much less useful.
There's also no way to understand it in terms of a few simple concepts for beginners. Do you want an override, an overlay, a flake, or something else? Does specifying an option in multiple places combine them, or does one spec override the other? It feels as though Nix is a technology of special cases, and the docs don't make it easy to understand what to do in each case when all you know is the kind of change you want to make.
The worst culprit of this is NixOS services, which each declare an ad-hoc API that I normally find myself digging into the service declaration file in the Nix repo to try and understand.
As someone who uses nix daily for work and home, I've found that there is always a nice concise way to accomplish what I want, but finding that solution is extremely difficult. It seems like the best (and sometimes only) documentation is the code itself, so until you get comfortable with the language you are missing a majority of the documentation. It's a catch-22, you have to know nix to learn nix. It really shouldn't have to be that way.
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.
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.
reply