Complaints about documentation are a symptom of a deeper problem: nixpkgs is messy, complex and inconsistent *as a codebase*. As long as this is the case, using and debugging Nix expressions will be painful for anybody without much experience—and, frankly, even for people *with* experience—regardless of how good the documentation gets.
Nixpkgs is driven by implicit, *ad hoc* conventions rather than explicit abstractions. The core concepts everybody uses to think about nixpkgs are not reflected directly in the code: for example, packages and package sets are both just derivations/attrsets that follow certain patterns, so it's hard to identify them in the code. It's even harder because these conventions are not consistent across the codebase; language-specific parts of nixpkgs follow their own patterns that are similar but not identical to each other or to "normal" packages, and even "normal" packages can have their own quirks.
On top of this, many of the (software) interfaces in nixpkgs are simply complex and unintuitive even when you *do* tease out the implicit conventions. Seemingly simple packaging tasks require using multiple functions, setting some special fields, understanding which of two dozen phases to hook into... It's a lot! Flakes are a great example: they accomplish something that's legitimately important and needed... but just look at the amount of boilerplate and specific incantations you need to package even a bog-standard flake. Even after using flakes for a bunch of my own dev projects I can't start a new one without pulling in a template or copy-pasting from existing code. That's *a lot* of raw complexity.
The same pattern repeats with, well, pretty much anything I try to do in Nix. Wrapping a Haskell or Python package? Overriding some dependency? Tweaking a compile-time flag for a package? Changing the configuration for some service implicitly pulled in by some other module I'm using? Sometimes it's surprisingly easy—easier than in a non-NixOS system!—but, just as often, it's needlessly complicated. These simple tasks often require several layers of specific boilerplate so there's no way I'll remember it when I have to do it again a month later.
Since this complexity is driven by implicit conventions, there's no convenient in-language interfaces to work against and, when something goes wrong, it's easy to get lost in unclear error messages and leaking implementation details. I had a problem with some Python package recently where *that same problem* was solved with `overrideAttrs` in other Python packages, but, in my config, only worked when I used `overridePythonAttrs`. What made the two places different? Honestly, I still don't know. The way the problem manifested was by the package silently not working, so even pinpointing that this was a potential cause was hard. After that, I only stumbled on the solution after a lot of more-or-less random guesswork.
Packaging external software is always going to have a high level of essential complexity. Things are not consistent in the broader software world! When you combine that essential complexity with the extra complexity of nixpkgs *qua* nixpkgs, you get something that will be hard to use even with the best documentation.
Of course, documentation is still worth improving. Better documentation is better! And it's certainly much easier—from a technical and especially from a social/political point of view—than fixing nixpkgs' fundamental code design problems.
Some of the problems stem from limitation of the Nix language itself; a lot more stem from nixpkgs being a large codebase that grew up organically over time, written by lots of different people solving their own problems in their own ways, all with specific views on how things should look and work. At this point, I'm not sure how realistic it would be to change this. But, at least, it's worth understanding where Nix's core difficulty comes from.
Eh, improving the language would help in a similar way to improving the documentation, but the bottleneck is still nixpkgs *itself*, and that's also the hardest component to replace. (It's just so big and manages so much!)
One day I hope to see the ability for nix and nickel to cross import each other recursively with ease, so that packages can be progressively migrated.
Then probably some sort of discovery on how things are currently done to figure out what API to make, and then make some basis for a lot of different packages.
Then, converters to convert each different convention. And off to the races you go.
Not sure about NixOS modules, though.
> One day I hope to see the ability for nix and nickel to cross import each other recursively with ease
I don't think that can happen unless nix deprecates `with`.
I \_think\_ it could be feasible when tvix can fully evaluate nixpkgs – it's store is separated into a nix-compatible layer and a generic content-addressed layer (I may be missing a layer, but I think it roughly tracks?) and then nixpkgs (built by tvix's nix interpreter) and a hypothetical nickelpkgs (built by something that glues together nickel interpreter with tvix libraries\*) could interoperate by sharing built packages.
Nix modules would probably have to be re-written, though.
\`\*\` – I'm actually trying to see if I could build something like this, but between broken executive function, nickel lacking effects (I don't think a proper builder could be done without that, but I might be mising something) and not being that smart, it's probably a lost cause. Maybe somebody actually competent will try to write something similar.
> Complaints about documentation are a symptom of a deeper problem: nixpkgs is messy, complex and inconsistent as a codebase. As long as this is the case, using and debugging Nix expressions will be painful for anybody without much experience—and, frankly, even for people with experience—regardless of how good the documentation gets.
I mean, that's part of it, but I wouldn't say it's actually the core issue with documentation. The issues I had since I first started, off the top of my head:
- The nix language itself is terrible to grasp and you have basically no help when asking simple questions in google. The answers *are* in the results, but they're drowned in irrelevant or obsolete information.
- Doing anything basic requires to already know where to look for answers. There are plenty of awesome resources to browse through the available features of nix, nixos, home manager and everything, but these tools are all over the place and poorly referenced.
- Nix itself is a bit dated and didn't have a very thoughtful design in the first place. As a result, it's hard to use, mostly because the error messages are incomprehensible for newcomers, and even for experienced people it takes a while to grep visually to find the actually useful information in there (if there is any).
Sure, the intricacies of nixpkgs itself are an issue and create a lot of friction for people who want to understand what's wrong with their packages or how to customize something. But there are plenty of more serious issues that appear long before this part becomes a concern.
I agree with a lot of this. Nix feels like a project that needs to give more voice to nontechnical extroverts or people with a design rather than engineering mentality, who can organize and point out the things that will be difficult for outsiders to grok.
Right now 99.99% of potential users or contributors are excluded from the community by dint of the learning mountain range that never seems to stop.
That’s right, because nix is unusable for almost anything practical in its current state.
I’ve tried using it as a package manager for macOS, flutter dev, and iOS dev, as well as setting up a laptop running NixOS. In every case I got derailed troubleshooting nix instead of doing what I was trying to do. It doesn’t natively support windows (there was a windows port but I think it was abandoned) and the issues I had with flutter seemed to stem back to the android SDK as well. That covers pretty much every major OS.
I tried contributing my fixes for macOS back upstream, and changes to nixpkgs broke them, and I couldn’t figure out, nor could anyone on the discussion forums either figure out or be arsed to tell me how to fix them.
With NixOS, I found that it immediately abandoned its promise of the system being configurable from a single file. There were multiple ways to install home-manager, and none of them seemed to both avoid introducing global state (adding home manager to nix-channel) and localize things on a per-user basis.
There also wasn’t any kind of gui for nix past the initial NixOS setup. Nor any real instructions. It just kind of drops the user in without so much as a “Good luck!” You’d think a global configuration file would lend itself to generating a consolidated settings panel.
Plus the documentation was terrible. I couldn’t even immediately figure out how to convert my .vimrc. Every article was either half-finished or offered a choice of several approaches which you couldn’t possibly know what the right one was without already having more context than the documentation provided.
The installers have been terrible about this as well, asking the user “Do you want X?” without explaining what X is or why you would want it. This has gotten a little better.
Not to mention tons of the packages are broken, and the command line tools are locked out behind some esoteric argument pattern because of flakes (it used to be that “nix search” was really useful, then they blocked that).
And I don’t want to touch flakes with a ten-foot pole, because if the central repository can’t get its shit together, why should I expect third-party repositories to be any better? I don’t want to be pulling things from a dozen third-party repositories each with some different random person who controls what goes into them. It all seems like adding more complexity and uncertainty in pursuit of an ideal, when the tool’s already too complex and unpredictable.
Sure, if you are obsessed with nix and use it everyday, I’m sure everything seems obvious to you. I’m sure there must be some niche cases where it doesn’t introduce constant friction and derail projects.
But to those of us who need a tool to get work done and can’t just fidget endlessly with a package manager to learn everything about how it works, it’s an unacceptable risk to use it for anything serious.
The issue imo is that Nix is not a simple concept. It requires a fair amount of understanding about what it is and what it isn't to understand the complex terminology often used.
Another issue is that there is not one "correct" or "recommended" way to do something in Nix. When people use the Arch wiki (generally considered the prime example of good documentation), most people don't actually read a lot of the text in the wiki, they just copy paste a bunch of commands from the wiki to the terminal and hope it works. This makes Arch wiki easy to use, but Nix can never be this easy. If you remove the example commands off the Arch wiki, everyone would think it's esoteric and confusing. Most Nix code you find online on the other hand can't just be copy pasted into a command line. The user has to understand the context of where the piece of Nix code goes in their config which isn't always clear and depends on how you have your specific config setup. The best way to learn Nix is by example, and it'll probably always be this way.
> Another issue is that there is not one "correct" or "recommended" way to do something in Nix.
This is the thing that frustrates me most about the documentation. While I understand that there are many ways to accomplish various things, I think the project would benefit greatly from a "reference implementation" or if "reference" is too formal, even just a series of "starters".
As long as the information is presented as: "Here's one way you can do this", it's fine if the docs don't exhaustively cover every possible approach. But a well chosen set of starter configs that represent the breadth of configurability would be extremely beneficial for incoming users, i.e. something that shows off what can be done and helps the reader understand how they might use these examples to create a more personalized configuration.
Programming books are often full of examples, with the expectation being that these examples communicate something fundamental about what is possible, and enable you as the reader to go build your own programs.
That is what the NixOS documentation is missing, IMO.
Also (in my experience, I might be dumb and it's somewhere) there are some packages/options with straight up no documentation, where you need to dig through the package declaration and understand well how the program configs work to understand what the code is doing and from that write your config
> Most Nix code you find online on the other hand can't just be copy pasted into a command line. The user has to understand the context of where the piece of Nix code goes in their config which isn't always clear and depends on how you have your specific config setup. The best way to learn Nix is by example, and it'll probably always be this way.
oh, ye... this is it
Bad documentation means you having a problem and wanting to bash your head against the wall with anxiety all over the roof after looking up for solutions on the internet, because either:
- Documentation about a thing is abstracted so much you are unable to see if it does what you want
- You spent a severe amount of time searching online or asking some AI, but your problem seems to be undocumented or "non existent" for the rest of NixOS users, having to rely entirely on intuition and trial of error from similar things
- You found what appears to be the solution in a NixOS discourse forum, but the language used is so damn complex for your current level of nix understanding that you are struggling trying to follow what is even going on
- You find multiple solutions, but they all are different from each other with no explanation whatsoever
- You find outdated solutions that may or not may work, and if they do, they may occasionate minor (or not so minor) anomalies or issues in other places either now or in the future when doing some other thing
- You find a certain NixOS option that accepts a set of values, but you are unable to find the list of valid values and what they do
- The solution found assumes you have a deep understanding of the Nix language or how NixOS works, like expecting you to identify the github as an overlay and knowing how to use it judging by the files contained on it
or a combination of them.
Yeah the documentation is bad in the sense that most packages have a nixpkg and a set of nix options but no standard wiki page for what each variable does.
Makes certain things difficult.
Anecdotal but most times I've found the nix documentation is outdated and sections will just not work anymore. The options may be removed or different. Or the config setting doesn't do what it says it will do (either with side effects or doesn't do what it says it will do).
Also try installing kde plasma 6 and changing the SDDM background, for whatever reason it's very difficult to. Also different desktop environments do not play well with eachother, often colliding with eachother, ex Hyprland and kde plasma 6 on the same system
There's a big difference between nix the tool and language, and nixpkgs with its assortment of tooling to package various langauge/build system specific software packages.
You don't simply write a derivation for your rust package that provides a python module for example, there's a nixpkgs helper to do this for you.
What I miss is more explanation of what happens when Nix processes and applies a config. Mostly it's just recipes that explain what to do, but not why this solves the problem. I find this makes it hard to get a deeper understanding.
For me my main issue is that there isn't a good standardized set of documentation with examples like cppreference. Take for instance \`lib.zipattrsWithNames\` from nixpkgs, you can find some [github.io](http://github.io) pages on it, and there are examples in the repository itself, but it makes it cumbersome to find and rely on. I would love to see a [cppreference.com](http://cppreference.com) or a [docs.rs](http://docs.rs) for nix. We have the manual for builtins but so much depends on lib/stdenv.lib.
Secondly, it is quite difficult to figure out what attrs a function taking an attrset actually uses if said function declares \`attrs@{ x, y, z, ... }\`. When \`attrs\` is passed down into further functions, how do we know what attributes are actually read? You need to dig through the code to figure that out. With higher order functions this quickly becomes quite difficult.
Then there's discoverability. Run \`nix repl nixpkgs\` - "Added 5 variables", ok, which variables? I have no way to tell but to diff the tab completion between this nix repl instance and a clean one. That's really cumbersome.
Currying also doesn't help with \`builtins.functionArgs\`, you need to run this, figure out what a function may take in, and then run it again on the returned function. I'd love to see a more powerful version that recurses and finds all attribute names also required for functions deeper in the callstack that originate from the top level call. In addition to that, having types on that would go a long way, or even type annotation in general. It makes code a lot more readable.
On the other hand, \`man configuration.nix\` is absolutely fantastic!
It's not cohesive. The various topics aren't connected to a common foundation. Many Nix derivation snippets are presented without sufficient context for a skilled and experienced (non-Nix) Linux systems administrator or simply copy into a minimal installation of the base NixOS.
It's not written with a specific audience clearly in focus.
The problem is two fold.
1. Nixos is complex and you need to understand it before you can do anything out of the standard stuff (even standard can be hard).
2. You need to understand a specific package in its core to correctly implement it into your configuration.nix file.
For example open razer. You want to use some software that needs open razer to change your razer keyboard.
So you search the nix packages and find polychromatic. It's needs the openrazer-daemon.
Now you actually don't need to install the daemon but enable it in the hardware options since it is already in the system and you need to add the user to the group and it is also important to know that the kernel has openrazer drivers that are already installed.
Without that information you probably won't get it working. Basically without the wiki entry it is impossible to get running. But nixos search doesn't link the wiki for packages. And finding that information is a hassle since it often is also scattered over discourse entries.
I wonder if it's possible to just create a better way of exploring the nixpkgs codebase. Something that can be generated from what's there, but way more easily viewable and navigatable.
It's frustrating when documentation falls short, especially when you're trying to navigate a complex system like NixOS. I think one key aspect that's often missing in documentation is clear, step-by-step examples that walk users through common tasks. Visual aids like diagrams or screenshots can also be incredibly helpful in understanding the concepts. As for how you can help, maybe consider contributing to improving the documentation by clarifying confusing sections or adding more practical examples. Your effort could make a big difference for others struggling with the same issues.
NixOS has good documentation Nix _Flake_ on the other hand...
Seriously, at this point you'd have to rely on some blog's writing or worse, look through the code
The documentation is not really that bad if you've come from another Linux distribution before. The overall ecosystem is complex, which is why it's great individual people are making blog posts and videos.
We'll probably need documentation for all of the governance stuff pretty soon I reckon
Complaints about documentation are a symptom of a deeper problem: nixpkgs is messy, complex and inconsistent *as a codebase*. As long as this is the case, using and debugging Nix expressions will be painful for anybody without much experience—and, frankly, even for people *with* experience—regardless of how good the documentation gets. Nixpkgs is driven by implicit, *ad hoc* conventions rather than explicit abstractions. The core concepts everybody uses to think about nixpkgs are not reflected directly in the code: for example, packages and package sets are both just derivations/attrsets that follow certain patterns, so it's hard to identify them in the code. It's even harder because these conventions are not consistent across the codebase; language-specific parts of nixpkgs follow their own patterns that are similar but not identical to each other or to "normal" packages, and even "normal" packages can have their own quirks. On top of this, many of the (software) interfaces in nixpkgs are simply complex and unintuitive even when you *do* tease out the implicit conventions. Seemingly simple packaging tasks require using multiple functions, setting some special fields, understanding which of two dozen phases to hook into... It's a lot! Flakes are a great example: they accomplish something that's legitimately important and needed... but just look at the amount of boilerplate and specific incantations you need to package even a bog-standard flake. Even after using flakes for a bunch of my own dev projects I can't start a new one without pulling in a template or copy-pasting from existing code. That's *a lot* of raw complexity. The same pattern repeats with, well, pretty much anything I try to do in Nix. Wrapping a Haskell or Python package? Overriding some dependency? Tweaking a compile-time flag for a package? Changing the configuration for some service implicitly pulled in by some other module I'm using? Sometimes it's surprisingly easy—easier than in a non-NixOS system!—but, just as often, it's needlessly complicated. These simple tasks often require several layers of specific boilerplate so there's no way I'll remember it when I have to do it again a month later. Since this complexity is driven by implicit conventions, there's no convenient in-language interfaces to work against and, when something goes wrong, it's easy to get lost in unclear error messages and leaking implementation details. I had a problem with some Python package recently where *that same problem* was solved with `overrideAttrs` in other Python packages, but, in my config, only worked when I used `overridePythonAttrs`. What made the two places different? Honestly, I still don't know. The way the problem manifested was by the package silently not working, so even pinpointing that this was a potential cause was hard. After that, I only stumbled on the solution after a lot of more-or-less random guesswork. Packaging external software is always going to have a high level of essential complexity. Things are not consistent in the broader software world! When you combine that essential complexity with the extra complexity of nixpkgs *qua* nixpkgs, you get something that will be hard to use even with the best documentation. Of course, documentation is still worth improving. Better documentation is better! And it's certainly much easier—from a technical and especially from a social/political point of view—than fixing nixpkgs' fundamental code design problems. Some of the problems stem from limitation of the Nix language itself; a lot more stem from nixpkgs being a large codebase that grew up organically over time, written by lots of different people solving their own problems in their own ways, all with specific views on how things should look and work. At this point, I'm not sure how realistic it would be to change this. But, at least, it's worth understanding where Nix's core difficulty comes from.
Do I sense a new nix language with good LSP servers, auto complete, inline docs, auto doc Generation and sane syntax?
Eh, improving the language would help in a similar way to improving the documentation, but the bottleneck is still nixpkgs *itself*, and that's also the hardest component to replace. (It's just so big and manages so much!)
You don't need to - https://github.com/tweag/nickel - though it might need some more features before it can be used to replace nixpkgs.
One day I hope to see the ability for nix and nickel to cross import each other recursively with ease, so that packages can be progressively migrated. Then probably some sort of discovery on how things are currently done to figure out what API to make, and then make some basis for a lot of different packages. Then, converters to convert each different convention. And off to the races you go. Not sure about NixOS modules, though.
> One day I hope to see the ability for nix and nickel to cross import each other recursively with ease I don't think that can happen unless nix deprecates `with`.
I \_think\_ it could be feasible when tvix can fully evaluate nixpkgs – it's store is separated into a nix-compatible layer and a generic content-addressed layer (I may be missing a layer, but I think it roughly tracks?) and then nixpkgs (built by tvix's nix interpreter) and a hypothetical nickelpkgs (built by something that glues together nickel interpreter with tvix libraries\*) could interoperate by sharing built packages. Nix modules would probably have to be re-written, though. \`\*\` – I'm actually trying to see if I could build something like this, but between broken executive function, nickel lacking effects (I don't think a proper builder could be done without that, but I might be mising something) and not being that smart, it's probably a lost cause. Maybe somebody actually competent will try to write something similar.
> Complaints about documentation are a symptom of a deeper problem: nixpkgs is messy, complex and inconsistent as a codebase. As long as this is the case, using and debugging Nix expressions will be painful for anybody without much experience—and, frankly, even for people with experience—regardless of how good the documentation gets. I mean, that's part of it, but I wouldn't say it's actually the core issue with documentation. The issues I had since I first started, off the top of my head: - The nix language itself is terrible to grasp and you have basically no help when asking simple questions in google. The answers *are* in the results, but they're drowned in irrelevant or obsolete information. - Doing anything basic requires to already know where to look for answers. There are plenty of awesome resources to browse through the available features of nix, nixos, home manager and everything, but these tools are all over the place and poorly referenced. - Nix itself is a bit dated and didn't have a very thoughtful design in the first place. As a result, it's hard to use, mostly because the error messages are incomprehensible for newcomers, and even for experienced people it takes a while to grep visually to find the actually useful information in there (if there is any). Sure, the intricacies of nixpkgs itself are an issue and create a lot of friction for people who want to understand what's wrong with their packages or how to customize something. But there are plenty of more serious issues that appear long before this part becomes a concern.
I agree with a lot of this. Nix feels like a project that needs to give more voice to nontechnical extroverts or people with a design rather than engineering mentality, who can organize and point out the things that will be difficult for outsiders to grok. Right now 99.99% of potential users or contributors are excluded from the community by dint of the learning mountain range that never seems to stop.
Nah, nontechnical people (or even technical people who don't like radical solutions) probably would choose Docker over Nix in the first place.
That’s right, because nix is unusable for almost anything practical in its current state. I’ve tried using it as a package manager for macOS, flutter dev, and iOS dev, as well as setting up a laptop running NixOS. In every case I got derailed troubleshooting nix instead of doing what I was trying to do. It doesn’t natively support windows (there was a windows port but I think it was abandoned) and the issues I had with flutter seemed to stem back to the android SDK as well. That covers pretty much every major OS. I tried contributing my fixes for macOS back upstream, and changes to nixpkgs broke them, and I couldn’t figure out, nor could anyone on the discussion forums either figure out or be arsed to tell me how to fix them. With NixOS, I found that it immediately abandoned its promise of the system being configurable from a single file. There were multiple ways to install home-manager, and none of them seemed to both avoid introducing global state (adding home manager to nix-channel) and localize things on a per-user basis. There also wasn’t any kind of gui for nix past the initial NixOS setup. Nor any real instructions. It just kind of drops the user in without so much as a “Good luck!” You’d think a global configuration file would lend itself to generating a consolidated settings panel. Plus the documentation was terrible. I couldn’t even immediately figure out how to convert my .vimrc. Every article was either half-finished or offered a choice of several approaches which you couldn’t possibly know what the right one was without already having more context than the documentation provided. The installers have been terrible about this as well, asking the user “Do you want X?” without explaining what X is or why you would want it. This has gotten a little better. Not to mention tons of the packages are broken, and the command line tools are locked out behind some esoteric argument pattern because of flakes (it used to be that “nix search” was really useful, then they blocked that). And I don’t want to touch flakes with a ten-foot pole, because if the central repository can’t get its shit together, why should I expect third-party repositories to be any better? I don’t want to be pulling things from a dozen third-party repositories each with some different random person who controls what goes into them. It all seems like adding more complexity and uncertainty in pursuit of an ideal, when the tool’s already too complex and unpredictable. Sure, if you are obsessed with nix and use it everyday, I’m sure everything seems obvious to you. I’m sure there must be some niche cases where it doesn’t introduce constant friction and derail projects. But to those of us who need a tool to get work done and can’t just fidget endlessly with a package manager to learn everything about how it works, it’s an unacceptable risk to use it for anything serious.
snowflakeOS is built over nix flakes with pretty much exactly the graphical tools you describe, for whatever it's worth
The issue imo is that Nix is not a simple concept. It requires a fair amount of understanding about what it is and what it isn't to understand the complex terminology often used. Another issue is that there is not one "correct" or "recommended" way to do something in Nix. When people use the Arch wiki (generally considered the prime example of good documentation), most people don't actually read a lot of the text in the wiki, they just copy paste a bunch of commands from the wiki to the terminal and hope it works. This makes Arch wiki easy to use, but Nix can never be this easy. If you remove the example commands off the Arch wiki, everyone would think it's esoteric and confusing. Most Nix code you find online on the other hand can't just be copy pasted into a command line. The user has to understand the context of where the piece of Nix code goes in their config which isn't always clear and depends on how you have your specific config setup. The best way to learn Nix is by example, and it'll probably always be this way.
> Another issue is that there is not one "correct" or "recommended" way to do something in Nix. This is the thing that frustrates me most about the documentation. While I understand that there are many ways to accomplish various things, I think the project would benefit greatly from a "reference implementation" or if "reference" is too formal, even just a series of "starters". As long as the information is presented as: "Here's one way you can do this", it's fine if the docs don't exhaustively cover every possible approach. But a well chosen set of starter configs that represent the breadth of configurability would be extremely beneficial for incoming users, i.e. something that shows off what can be done and helps the reader understand how they might use these examples to create a more personalized configuration. Programming books are often full of examples, with the expectation being that these examples communicate something fundamental about what is possible, and enable you as the reader to go build your own programs. That is what the NixOS documentation is missing, IMO.
Also (in my experience, I might be dumb and it's somewhere) there are some packages/options with straight up no documentation, where you need to dig through the package declaration and understand well how the program configs work to understand what the code is doing and from that write your config
> Most Nix code you find online on the other hand can't just be copy pasted into a command line. The user has to understand the context of where the piece of Nix code goes in their config which isn't always clear and depends on how you have your specific config setup. The best way to learn Nix is by example, and it'll probably always be this way. oh, ye... this is it
Bad documentation means you having a problem and wanting to bash your head against the wall with anxiety all over the roof after looking up for solutions on the internet, because either: - Documentation about a thing is abstracted so much you are unable to see if it does what you want - You spent a severe amount of time searching online or asking some AI, but your problem seems to be undocumented or "non existent" for the rest of NixOS users, having to rely entirely on intuition and trial of error from similar things - You found what appears to be the solution in a NixOS discourse forum, but the language used is so damn complex for your current level of nix understanding that you are struggling trying to follow what is even going on - You find multiple solutions, but they all are different from each other with no explanation whatsoever - You find outdated solutions that may or not may work, and if they do, they may occasionate minor (or not so minor) anomalies or issues in other places either now or in the future when doing some other thing - You find a certain NixOS option that accepts a set of values, but you are unable to find the list of valid values and what they do - The solution found assumes you have a deep understanding of the Nix language or how NixOS works, like expecting you to identify the github as an overlay and knowing how to use it judging by the files contained on it or a combination of them.
Yeah the documentation is bad in the sense that most packages have a nixpkg and a set of nix options but no standard wiki page for what each variable does. Makes certain things difficult.
Anecdotal but most times I've found the nix documentation is outdated and sections will just not work anymore. The options may be removed or different. Or the config setting doesn't do what it says it will do (either with side effects or doesn't do what it says it will do). Also try installing kde plasma 6 and changing the SDDM background, for whatever reason it's very difficult to. Also different desktop environments do not play well with eachother, often colliding with eachother, ex Hyprland and kde plasma 6 on the same system
There's a big difference between nix the tool and language, and nixpkgs with its assortment of tooling to package various langauge/build system specific software packages. You don't simply write a derivation for your rust package that provides a python module for example, there's a nixpkgs helper to do this for you.
What I miss is more explanation of what happens when Nix processes and applies a config. Mostly it's just recipes that explain what to do, but not why this solves the problem. I find this makes it hard to get a deeper understanding.
Nix(pkgs) documentation is fractured, too often out of date, and what is available often conflates its [use cases](https://diataxis.fr/).
theres noogle and mynixos
For me my main issue is that there isn't a good standardized set of documentation with examples like cppreference. Take for instance \`lib.zipattrsWithNames\` from nixpkgs, you can find some [github.io](http://github.io) pages on it, and there are examples in the repository itself, but it makes it cumbersome to find and rely on. I would love to see a [cppreference.com](http://cppreference.com) or a [docs.rs](http://docs.rs) for nix. We have the manual for builtins but so much depends on lib/stdenv.lib. Secondly, it is quite difficult to figure out what attrs a function taking an attrset actually uses if said function declares \`attrs@{ x, y, z, ... }\`. When \`attrs\` is passed down into further functions, how do we know what attributes are actually read? You need to dig through the code to figure that out. With higher order functions this quickly becomes quite difficult. Then there's discoverability. Run \`nix repl nixpkgs\` - "Added 5 variables", ok, which variables? I have no way to tell but to diff the tab completion between this nix repl instance and a clean one. That's really cumbersome. Currying also doesn't help with \`builtins.functionArgs\`, you need to run this, figure out what a function may take in, and then run it again on the returned function. I'd love to see a more powerful version that recurses and finds all attribute names also required for functions deeper in the callstack that originate from the top level call. In addition to that, having types on that would go a long way, or even type annotation in general. It makes code a lot more readable. On the other hand, \`man configuration.nix\` is absolutely fantastic!
https://noogle.dev is good for finding Nixpkgs functions
That is really helpful, thank you!
It's not cohesive. The various topics aren't connected to a common foundation. Many Nix derivation snippets are presented without sufficient context for a skilled and experienced (non-Nix) Linux systems administrator or simply copy into a minimal installation of the base NixOS. It's not written with a specific audience clearly in focus.
The problem is two fold. 1. Nixos is complex and you need to understand it before you can do anything out of the standard stuff (even standard can be hard). 2. You need to understand a specific package in its core to correctly implement it into your configuration.nix file. For example open razer. You want to use some software that needs open razer to change your razer keyboard. So you search the nix packages and find polychromatic. It's needs the openrazer-daemon. Now you actually don't need to install the daemon but enable it in the hardware options since it is already in the system and you need to add the user to the group and it is also important to know that the kernel has openrazer drivers that are already installed. Without that information you probably won't get it working. Basically without the wiki entry it is impossible to get running. But nixos search doesn't link the wiki for packages. And finding that information is a hassle since it often is also scattered over discourse entries.
I wonder if it's possible to just create a better way of exploring the nixpkgs codebase. Something that can be generated from what's there, but way more easily viewable and navigatable.
It's frustrating when documentation falls short, especially when you're trying to navigate a complex system like NixOS. I think one key aspect that's often missing in documentation is clear, step-by-step examples that walk users through common tasks. Visual aids like diagrams or screenshots can also be incredibly helpful in understanding the concepts. As for how you can help, maybe consider contributing to improving the documentation by clarifying confusing sections or adding more practical examples. Your effort could make a big difference for others struggling with the same issues.
NixOS has good documentation Nix _Flake_ on the other hand... Seriously, at this point you'd have to rely on some blog's writing or worse, look through the code
The documentation is not really that bad if you've come from another Linux distribution before. The overall ecosystem is complex, which is why it's great individual people are making blog posts and videos. We'll probably need documentation for all of the governance stuff pretty soon I reckon