I'd partially blame the software as well. You can't standardise what doesn't want to follow standards. A lot of software or their developers work against the Nix model, some do so actively. The most visible example is the XDG-BD standard (https://wiki.archlinux.org/title/XDG_Base_Directory), but there are a bunch of other things like that which make packaging difficult.
Like the other commenter mentioned how npmlock2nix exists but it's hard to figure out that these tools exists.
Im hoping that flakes help solve alot of problems to make it easier for users to jump in. Then hopefully the documentation problem will naturally start going away as more people start using nix.
The main pain points people identified:
- Getting started with Nix is hard.
- The documentation isn't great for getting started, for getting some task done, and is spread across many places.
- Debugging bad Nix code is hard.
- Contributing back to Nix is hard.
Despite the above, I think most of the respondents had just started using Nix within the last year or two.
I think some of the Summer of Nix effort is towards improving documentation. e.g. https://discourse.nixos.org/t/summer-of-nix-documentation-st...
Python has docstrings, Java has javadoc, Hare has haredoc, Lua has emmylua... etc. Every language has SOME WAY of leaving explanation on what a function does, and what values it takes. Nix doesn't seem to have such a thing (if it does, it's a well-kept secret!).
Functions being lazy doesn't help, since that makes it very hard for tools to provide feedback without actually executing the right codepaths. And finding the definition of a function is HARD.