I know that what I’m about to say will be unpopular here. I think documentation needs to be created towards agents more and more. Users will are using agents to gather information these days, llms.txt will be the hear and soul of Nixos documentation in the near future. This solve some of the problems and we can automate the updates of this easy. The Nix community should embrace and guide the usage of Ai in nixos. We can be the compass, already so many companies are combining nixos and AI. When it comes to different distro’s and Nix: I love NixOs. How about proper guides for users that want to create them based on Nix. When Omarchy came out it blew my mind how easy things can be. Most users that switch to Linux take long time to find apps and services they want to use, they are more amazed by what is already there … We could be like that. I have tried to copy that in my attempt to do this based on Omarchy spirit when I created Nixarchy for myself. Times have changed, user base is changing, if Nixos is to survive we need to change as well. The solutions is not gate keeping, and using politics for every conflict and everything we do not agree with. , “I disapprove of what you say, but I will defend to the death your right to say it”.
It’s not that simple. In France, for example, inciting hatred is illegal (history has taught us why), and this is not considered an infringement on freedom of expression. Regarding AI, a little reflection shows that the negative aspects cannot simply be ignored. That is the reality of the world today: we can either pretend not to see the implications or try to find other paths. Also, as a human, I like to understand software—including through its documentation—and when that documentation is well-crafted, it is a real pleasure.
And I do agree with that.. but one thing does not exclude the other. Time and history has showed us time and time again that changes like this can not be stopped, you be part of the change and show new users what they can do and how with examples but excluding them and using politics does not work. You do not ignore nothing, you create a choice with value. We are doing the same thing that the other side have done to “us” again and again. Why do we not learn from the mistakes?? What I’m trying to say is include and not exclude, teach and embrace with changes, be better but with examples, if we want users to be better with AI let us show them how. If not Nix we be gone .. the money will be gone.. companies will not invest or support. Be pragmatic but keep the moral sense. anyway … tech is for fun and profit 
we need more fun these days lets make it fun again.
I was about to give an actual answer but then I remember what thread we’re in. [Moderator’s note: this series of posts was moved from Omarchy and NixOS.] It’s all been addressed. Repeatedly.
Have you considered reading the thread and the arguments people have made?
Because honest engagement can’t be outsourced to a chatbot.
“Just do what I want” does not work that well on humans.
I don’t agree. I work in AI, I use AI a lot, but relying on AIs for too long and reading their output is a sure way to ingest brain asbesthos.
Documentation should be for the users first, then for the developers, and only then for agents.
I’ll take the first portion of the post as the main topic: how to make it easier for agents/AI to be better at managing/using/manipulating/working within the Nix and Nixpkgs ecosystem. As you know, this is a contentious topic.
It is not likely that we will resolve question of AI in this moment. So I’ll propose a way past this; reduce the contention. Create and start a project to make such documentation, skills, tools, guides, whatever, in an new repo. Make it usable as a sidecar or an easy reference point for agents to find and prove its usefulness over period of time. Find other collaborators and contributors for that effort. This means there isn’t an argument over what “makes it into Nixpkgs” and you have a chance to prove that it is useful and demonstrate it doesn’t devolve into an unmaintainable mess. People that want to opt-in can; and those that want to opt-out don’t need to do anything.
I do want to address a concern that was brought up to me, paraphrasing: “we cannot keep up”. That if AI is allowed to do to much in the ecosystem, non-AI users will get pushed out over time. Partly due to the quick iteration and volume of output from AI users as well as making it much more difficult for anyone who wishes to strictly avoid interacting with AI generated content or code. Yep, this is true, but I’d much rather manage that phenomenon than ignore it - create spaces for different people to engage in the manner that they wish. I also don’t want Nix as a whole to be the one that “cannot keep up”.
So that’s my suggestion: don’t try to change everyone’s mind in debate, (you won’t be able to anyway). Build the thing you want, find others that are interested in the same thing, and show the value over time. Spend your time trying to find others who share your vision. Then you can propose it to be included into the NixOS org, as a standalone repo or offer it to be included into existing repos, or whatever is appropriate.
- i’m unsure why you believe that a linux distribution almost exclusively centered around being able to manually put together exactly the system you want in a declarative fashion would be best served by throwing it into what is, for most people, a magic black box and simply hoping that what shakes out is shaped as you want.
- i’m unsure why you believe that after literally billions of freedombucks have been poured into the natural language processing side of llms (given, you know, their name) that the best course of action is to throw all of the documentation in the bin and write up “specialised” versions of it that, generally speaking, are just extremely verbose versions of the “real” documentation - documentation that would better serve both parties if it was just the normal documentation, because then you have a way to counterbalance the “oracle”.
have you actually used these systems in depth?
the solution is not … using politics for every conflict
ah, another “keep politics out of tech”. many such cases.
this may surprise you, but code doesn’t just appear from nowhere.
i will not “defend to the death” your right to say it, and neither will you.
Doesn’t this still create the problem that documentation which should really be available to humans is instead cordoned off and optimized for LLMs? Whether that’s an AGENTS.md in your repo or in some “sidecar” like this, the stuff that’s useful to LLMs is usually stuff that should be documented in general, not just for LLMs. i.e. These kinds of sidecars rob the humans of documentation in favor of LLMs.
It might, yes. Or not. Hard to predict.
We’ve been trying to improve the documentation for a long time. I remember this being a goal talked about a decade ago. I don’t think this is an either-or situation. If we can harness some of this enthusiasm and improve documentation/guides/tutorials that are easy for LLMs to use… it is quite likely it will be something that makes it easier for humans. Or it might turn out that those LLMs can educate humans better. Or we can reduce the toil in the ecosystem. Or it may be totally useless for humans; it doesn’t degrade existing documentation and there is a chance we can find a way to improve both.
This isn’t theoretical. I’ve actually found the rapid growth of doc/plans.md and .skills/ to be an improvement over having no documentation at all. It reveals a bit of intention. At least people are sharing the context/prompts so that we have an idea of what the LLMs are ingesting rather than only seeing the output. The choice might not be “does person X create human or LLM docs” - but rather “does person X create LLM docs or nothing”.
So no, it doesn’t rob humans of existing documentation - the whole point of my suggestion is to reduce contention. They can make serious progress without impinging on anyone else. Here is someone willing to do some work and take a bet on a certain approach. I do hope the work and efforts are useful generically. Let them try.
If we can get people to create better nix documentation under the guise of “it’s for the clankers” and that documentation then is more concise, more condensed, and more useful than the current stuff, that’s a win.
If it isn’t, roll back the PR.
Actually getting any benefits from (absolutely real) NixOS overhead in some areas requires more understading than with many other distros; LLM might help navigate but the user not understanding the docs won’t get much benefit.
When LLMs are in shape to figure things out, they absolutely manage with human-targeted documentation; ease-of-grepping considerations apply to human-targeted quick-reference too.
If it is an improvement to documentation for humans and incidentally also for automated agents, I don’t think original motivation should be considered a blocker. If it is not good documentation for any person — is it worth the effort given that next quarter’s LLMs will behave differently enough to make the current overfitting counterproductive?
But this is the point of this exercise right!? Start somewhere and find the right balance. But we need to start somewhere. I agree most of this can be too long but lets start and make this good. Most of users are already using Skills that they are creating them self. Why not help them out. How to use best practices, keep the code clean and more.
They do not have to do that. For some lazy users sure .. for users that have used system for sometime and want to learn more, I do not think so. That is at least my experience from talking to new users that fall in love with Nixos. Easy start and then learning more
…?
Also, platitudes like
don’t mean anything if you don’t defend your views with a source. Is nixos dying? How do you know? Will gearing more towards LLMs and less towards humans help?
Again one does not exclude the other. How many big tech companies are using Nix today? How many could adopt Nix tomorrow? What is stopping them from doing that? I do not say that all the big tech should use Nix but knowing how much value Nix brings they should. So what is stopping them from doing that? Value, ease of implementation, documentation. We can leave the other stuff out of this for now. This is why we see Omarchy getting so much attention, they are doing something different. Not saying that Nixos is dying but a change is coming we all can see that and I want us to be a part of that.
i actually quoted your own op for the “no politics in tech” things and didn’t insert anything (i removed “not gate keeping, and”). i apologise if that was unclear.
anyway, i think you’re misunderstanding me. i’m objecting to your framing that we should be expending the constrained documentation effort we have on documentation “towards llms”. the issue’s “symptom” appears to be that you wanted to create omarchy-but-nixos, asked an llm to help, and it struggled to assist as well as you’d expect. is that correct? if so, i don’t really think the solution is “agent-oriented documentation”. where would that leave you as both the user and the maintainer alongside claude?
like i said, you need to be able to counterbalance the oracle. you need to be able to critically analyse what has come out of your llm’s response to your query, but to do that you need actual sources and documentation, so now you have to go dig through this “agent-oriented documentation” because the effort is there now. it’s not a good cycle to be in and makes the experience even worse. people who aren’t using llms begin to miss out - because llms can punch through information way faster - and can’t keep up with the verbosity that ends up in that agent-oriented documentation because it ends up being written by llms and curated by people used to llm outputs.
They do not have to do that. For some lazy users sure .. for users that have used system for sometime and want to learn more, I do not think so. That is at least my experience from talking to new users that fall in love with Nixos. Easy start and then learning more
i think you’re really underestimating the % of people (in general, not just nixos enthusiasts, linux users, or in tech) who prefer to get a pre-prepared solution. it’s kind of difficult to go from there if you aren’t sure how you got there which… i’m unsure anyone wants that in an operating system.
How many big tech companies are using Nix today?
not heaps.
How many could adopt Nix tomorrow?
not heaps.
What is stopping them from doing that?
unfortunately, decades of institutionalised knowledge of the current way. llms being able to understand nix tomorrow won’t change that, the upending of which would cost billions.
and I do actually agree with that. But there are ways to do this correctly. Right? LLM’s are dumb but they are really useful for many things. Documenting is one of them. Testing and making the documentation better as well. We should give people a choice and make it easier to lookup and find the right docs. That is all. Nix is so unique and so well done. I just think it should have the place it deserve in the industry, and sometimes I feel the gatekeeping is to strong. I do not accept that we can not do anything, we can and we should. The question is what? This is why we should talk about this and prepare for the future as best as we can. Agreed? I don’t have the answers but a lot of question and some ( maybe stupid ) ideas.
reading, very much. writing, not really - mostly because “reading, very much”.
as a somewhat obtuse example, the agents.md file in your nixarchy repo spends 144 words explaining that CLAUDE.md is a symlink to AGENTS.md for compatibility reasons (that’s nine words). ordinarily this means nothing to you, because as a human this file (generally) isn’t for you. it means nothing to an llm, because they punch through information like nobody’s business. but it means a lot for a user who has to use that documentation as the primary source. if documentation like that becomes documentation that we’re spending effort on, the effect is way more negative than you’d hope.
i’m reminded while peeping that file that i find text from an llm more tiring to read. i don’t really know how to describe it other than it feels like i’m constantly reading headlines.
on the other hand, llms can read and “understand” actual human-oriented documentation just fine.
exactly. But adding the guide and showing users and making an effort is what is needed. I think just by explaining this to most new users we would solve a lot. We should also have a way to create and maintain official skill for agents. Even if they just point to the public documentation.