Yeah, and that's obviously pretty hostile when the best guide is reading the source.
I think the deeper problem that maybe isn't always considered in the "Nix needs better docs" discourse is that there are many tasks that simply don't have an optimal workflow in Nix (yet). It can be weird documenting how do some particular thing, but having to frontload that doc with a bunch of caveats about which particular set of tradeoffs the suggested approach is embracing.
For example with Python, a huge one is around how much you want to leverage the Python packages already in nixpkgs. If you want to use them, which makes sense if you don't really care about versions or you've got a lot of things with tie-ins to non-Python such as bindings packages, then you probably want the conventional buildPythonPackage workflow, where you manually package any missing deps, perhaps assisted by pip2nix: https://wiki.nixos.org/wiki/Python
But if you have a self-contained app that already has everything locked and you just want minimum friction, then you almost certainly want uv2nix: https://github.com/pyproject-nix
A lot of things in Nix are like this. Same story with containers where you've got dockerTools.buildImage but depending on your workflow nix2container is almost certainly the better choice. Nix's limitations around IFD are finally being addressed by https://tvix.dev/ but that's a rewrite and brings yet another potential split.
Nix is the epitome of being perpetually stuck in the 1000 flowers blooming [1] state of things, and in some ways that's beautiful, but it needs people to build a cathedral or two within the bazaar. Determinate [2] is trying, but they've also taken some heat from the community for concerns around OSS and governance.
That's an excellent way to put it! Also, never read the 'Let 1000 Flowers Bloom' article, thanks.
What I find extremely interesting, is I would give (and have given) exactly same advice to someone asking me about python or docker packaging. Which means that we both ended up with the same long struggles and rabbit holes independently. It would certainly be excellent if those cathedrals in the bazaar were more centrally known and documented, to concentrate efforts, and to help others avoid having to spend so much time doing the same.
The Nix world is not a huge place. I was largely self taught for about a year and then heavily influenced by working with Numtide, so a bunch of my tools experience comes from them.
I think the deeper problem that maybe isn't always considered in the "Nix needs better docs" discourse is that there are many tasks that simply don't have an optimal workflow in Nix (yet). It can be weird documenting how do some particular thing, but having to frontload that doc with a bunch of caveats about which particular set of tradeoffs the suggested approach is embracing.
For example with Python, a huge one is around how much you want to leverage the Python packages already in nixpkgs. If you want to use them, which makes sense if you don't really care about versions or you've got a lot of things with tie-ins to non-Python such as bindings packages, then you probably want the conventional buildPythonPackage workflow, where you manually package any missing deps, perhaps assisted by pip2nix: https://wiki.nixos.org/wiki/Python
But if you have a self-contained app that already has everything locked and you just want minimum friction, then you almost certainly want uv2nix: https://github.com/pyproject-nix
A lot of things in Nix are like this. Same story with containers where you've got dockerTools.buildImage but depending on your workflow nix2container is almost certainly the better choice. Nix's limitations around IFD are finally being addressed by https://tvix.dev/ but that's a rewrite and brings yet another potential split.
Nix is the epitome of being perpetually stuck in the 1000 flowers blooming [1] state of things, and in some ways that's beautiful, but it needs people to build a cathedral or two within the bazaar. Determinate [2] is trying, but they've also taken some heat from the community for concerns around OSS and governance.
[1]: https://news.ycombinator.com/item?id=10294833 / https://gigamonkeys.com/flowers/
[2]: https://determinate.systems/