I'd love NixOS more if they had any decent documentation.
Everything seems scattered around a dozen forums, a hundred old blog posts, and a thousand issues of "this work on my machine (3 releases ago)".
Everything seems scattered around a dozen forums, a hundred old blog posts, and a thousand issues of "this work on my machine (3 releases ago)".
wiki.nixos.org claims that nixos.wiki is outdated and unofficial. But both appear to receive updates, and which one wins the SEO game is a coinflip whenever i google a nixos question.
And that's what's great about NixOS, you just clone nixpkgs and treat it like any other underdocumented software you might work on.
As a software engineer I have an opposing attitude towards this. I work on projects with terrible documentation because somebody pays me to do so or there is a significant potential that I can unlock.
There are significant alternatives to NixOS like bootable containers and OSTree which are more useful and better documented. If Nix project really cares about being competitive and adopt users, they have to document their stuff. They are already going against the grain and ain't nobody has time to put up with their weird language and their subpar documentation.
I mean, I'd argue there is significant potential, but really, for me it's just easy because I've been doing it for 20 years, and documentation is always fundamentally worse than code in some important ways.
> If Nix project really cares about being competitive and adopt users, they have to document their stuff.
This is one of the good/bad things about OSS.. most users don't provide positive value to the project. So do they really want to adopt users? Shrugs but the project is certainly competitive.
C’mon, just drop the “greybeard” act. Nix not having proper documentation is bad practice, period. No ifs buts or howevers, it’s just an objective fact. Good documentation is always (ALWAYS) a net positive, and this is an OS with it’s own unique mindset and way of doing things, good documentation is essential. End of.
Claude Code has to be actively steered, because while it knows some nixpkgs it surely doesn’t know it enough. E.g. it was absolutely incapable of fixing lldap settings after system upgrade from 25.05 to 25.11. It just prodded around blindly, producing meaningless configs instead learning how the module works.
NixOS docs work for me, but I tend to just go for the nixpkgs source instead. Manuals document options but not how those are actually plumbed through, nor what remains behind the scenes like all systemd unit settings). Claude can do this too, but it goes quite weird roundabout ways with a lot of weird `find /nix/store` and `nix eval`s to get to it, slow and token-hungry (and not always accurate).
This said, Claude is very helpful at checking logs and providing a picture of what’s going on - saves ton of time this way. Plus it can speed up iterating on changes after it’s fed enough knowledge (but don’t expect it to do things right, that’s still on you). It has breadth of it, but not the depth, and that shows at almost any non-trivial task.
I feel you on the nix store + nix eval death loop, though it gleans real info. If I weren't on the Claude Max plan I'd probably feel more of the pain. And context is now 1MM tokens which means you're not running out just as it's starting to piece things together, heh.
I’m going to experiment with skills next, or maybe make it build a few helper scripts for itself to quickly get some module source from nixpkgs matching flake.lock without having to think of it all. I’m positive about Claude for nix management, merely saying it’s not something that “just works” for now and reading nix code is still on the human part of the tandem.
This said, to be fair - when it gets the approach right, it excels. I was setting up Ente for photos backup and sharing, and it produced a nice overlay with custom patches for my needs from just “figure out why /shared-albums/ redirects wrong and fix”. Found the module, the package, pulled source, analyzed it, proposed a patch (settings weren’t enough), did it - I only had to test, and only because I haven’t provided it with a browser. Felt amazing.
Unless you're brand new to Linux or computing, it's not a mystery what a given nix config change is ever doing.
You can probably guess what this does:
networking.firewall.allowedTCPPorts = [ 8080, 9000 ];
I am not brand new - and I don't know what the heck the config is doing.
That is why I rely on documentation.
The "code is self-explanatory" is always an attempt to not have useful documentation and try to rationalise that problem away.
You can read documentation on an as-needed basis or to your heart's content.
The point is that the majority of the day to day changes I make to my desktop environment aren't so critical that I need to do more than read an AI agent's proposed changes to my config and accept them when they look reasonable.
And I don't think looking up the exact config options to NixOS' networking system does anything to increase my knowledge of the OS. It's just a triviality.
NixOS does you one thing better by giving you the option to configure things without caring about the underlying implementation, like whether the firewall uses iptables or nftables or something else.
Fails to parse is what it does...
Are we really living in times where people can't write a single (syntactically) well-formed line of code in a programming language they use?
I understand this doesn't really matter when just using NixOS Slop Edition™ but man I hate it.
Jeez, tough crowd.
Though it also kinda represents this pride over triviality that some people latch on to in the AI world which is odd since it's also only a mistake a human would make. Had I run my hand-written comment through a proofreading clanker, I would have spared you the negative emotional reaction.
In the pre-AI world, you would have probably not been so harsh since it's understandable that someone make that mistake with such an idiosyncratic language like nix that almost nobody writes full-time. Yet in the AI world, you demand more from humans.
Something interesting, there.
People are being more demanding of humans because humans are taking knowledge and learning for granted. All this abstraction has a cost, and the cost is you.
Despite many years of experience, I still sometimes get this wrong in Python or its equivalent in the other languages I regularly switch between:
from math import sqrt as s
import sqrt as s from math
import sqrt from sqrt as s
And suddenly we pretend that had I just written it by hand a few more times, I would never err again in forum comments, despite making similar errors this week in languages I've used to write millions of lines of code across decades.
That's true, and I should've been less rude in my previous comment. Sorry.
(Though note `nix eval` would've sufficed, no need for the probabilistic kind of clanker)
> Yet in the AI world, you demand more from humans.
But this isn't true. In my opinion `learning >> depending on an LLM` and my gripe is that it seems like the former is being displaced by the latter. In the pre-AI world I would've known that the person making the mistake wasn't making it because they outsourced their skill.
So I'm not, in fact, demanding anything more than in the pre-AI world.
I think the initial migration towards nixOS is the hardest point, since it requires learning a bunch of new things all at once in order to get the system into a usable state that matches your expectations and preferences. The key benefit of using an LLM is that it makes it really easy to get your system into a useful initial state, and then you can safely learn and experiment incrementally with a mix of tools.
When I started off I didn't understand everything, but at this point I feel I have a very good understanding of everything in my configuration file.
Like what is ultimately the difference here for you vs a non-nix user who, as author says, is just dealing with some big ambiguous pile of state? It kind of takes away any upside to using nix, and probably just creates more friction for your AI than just running ubuntu/apt stuff.
The idea is you can keep configuration "in your head" such that you can reason and iterate and fully know what your system is like at any moment. If you actually don't care about that, you aren't getting anything out of it!
I have these packages installed and these firewall settings and these users with these permissions and this folder served over Samba and these hotkeys that do these things and these Obsidian vaults synced over SyncThing and these devices in my SyncThing network and Neovim installed with these plugins and ...
This is difference between me and a non-nix user, not whether we can rattle off the exact state of our live system from memory.
The non-nix user has to query live system state, if such query tools even exist for their question, and I get to read a config file. And I get to maintain my system config in git, and I get to deploy my config on all of my machines.
Well the main difference is precisely that I have a clear opportunity to read and understand the declarative file.
But even if something were to sneak in there, rolling back is now trivial.
Also HN: No idea how this OS works, screw writing proper documentation, just ask Claude to do it! Wee!
You AI babies seriously need to pick a lane.