> 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.

> 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.

I used NixOS and Home-Manager to run my entire system and home directory for a couple weeks earlier this year. The lack of clear documentation made me leave. Most of the time to find relevant information I'd have to go in some chat room since often the "official" documentation would be outdated. If the documentation was better I'd probably still be on it.

All the official documentation is autogenerated daily. What documentation did you find outdated?

Autogenerated documentation !== up-to-date and/or good documentation.

Autogenerated means "we take these particular strings and texts and dump them in a different format". It says nothing about whether they are even remotely up to date.

Sure, but in my experience the documentation from the source has always been correct. There is tons of stuff on other websites that is outdated, but the source documentation has not suffered the same atrophy.

More importantly, much of the documentation is auto generated not from arbitrary doc strings, but from the nix expressions themselves. IE: https://search.nixos.org/options?

So I believe there was another source of the misinformation then the official docs.

One example: nix-pills introduces nix-env -i[1] as the third "pill" -- isn't this basically deprecated and never recommended by serious uesrs?

[1]: https://nixos.org/guides/nix-pills/enter-environment.html

Most probably NixOS Wiki, it's not official but always comes up as the top result because the manual's titles are irrelevent when you're trying to solve a specific issue. The NixOS Wiki is very helpful in a lot of ways (there is more info than in the manuals and you don't have to troubleshoot for hours because you missed activating some options), butit is true that it is sometimes outdated :/

Too that I say look at react hooks. Somehow the React devs managed to introduce functional concepts into a framework without anyone knowing why or how this black magic trick works. At the time of introduction I was heavily interested in functional approaches, mainly the solutions from Haskell. And now nobody gives a a damn how hooks works in JS only that they make the coding somewhat easier and nicer. (I‘m no JS developer and how no real world view at the current stage anymore).

Regarding nix. I love the idea and the project. Tried it 3 times with various issues which stopped me from using it (last time I was not able to compile a rust program because of some weird c runtime library which was pulled with the wrong version from wherever by whoever). My second bigger issue with nix is the fact that you have to go all the way or it makes no real sense. Mixing nix with Ubuntu or base arch is of course possible. But the developing python or whatever whichever means to install and manage the whole toolchain and project dependencies also with nix. I still check the project every now and then.

nix has been around for 18 years. If the documentation is still sparse after all these years, it's not a problem that will be fixed, ever. Same for explaining concepts.

Proper errors are a huge and poorly understood problem, so I'm inclined not to judge those too harshly.

I don't think it is fair to judge a project for the number of years its been around, specially for something that is really novel and innovative. Nix/NixOS is not a new web framework that most of concepts are really clear for everyone working with Web. It is a brand new concept for Operating Systems, however most people don't have a clue about system immutability and reproducibility and why this is so hard.

Of course, this doesn't excuse the state of the documentation that should be better. It is just that nobody ever documented this kinda of things before, so it is difficult to do it better.

Nix and NixOS just started to get more known and become popular from the last ~5 years or so, and I think this made the whole community aware that documentation is an issue and it is getting better and better (but maybe not at the pace most people wanted).