Yes, this frequently turns out to be the only resource I can find. But there is a significant cost to reading the source in order to understand something, compared to having a high-level explanation. This becomes especially important when you are on a deep stack of yak-shaving efforts. When I am trying to find a solution to a problem, which itself is an attempt to find a solution to a problem, which itself is … it would be good to get some idea of whether any specific thing might be relevant or not, QUICKLY.
Exploring the exponentially growing tree of yak-shaving components by having to read the source of each item, is, for me at least, an intractable problem. But maybe I’m just too dim.
A search engine.
More often then not, such searches suggest something, more or less relevant, in the Nix (or nixpkgs) manual, on the Nix pills. But I rarely go to those resources myself directly, because they are so vast, that you need a search engine to find what you want in them, anyway. Well, the manuals are a on a single (huge) page, so sometimes (rarely) I try those directly, but the pills, being spread over multiple pages, I almost always acces via a search engine.
Indeed.
I can’t quite put my finger on the reason, but I struggle to find Nix-related answers much more than in other technical areas, but I’m sure that part of it is this:
… the documentation is both huge and yet sparse.
You mention missing fine details, but I also find that the big picutre is often absent.
One might think of the documentation as being at four different levels
- Global overview of Nix.
- High-level description of sub-topics. Strategies for achieving different kids of goals.
- How to do some specific things.
- Detailed and comprehensive documentation of individual components.
In my eyes, level 1 is covered adequately.
Most of Nix documentation seems to be on level 3, and if what you’re trying to do happens to be covered, you’re in luck, if not …
Level 2 is where I feel the pain most acutely. Here I usually end up finding something vaguely related on level 3 and frequently find myself trying to fit a square peg into a round hole, thinking that there must be a better and more direct way of doing what I’m trying to do.
Level 4 appers to be mostly non-existent, in relative rather than absolute terms: there may be much that is documented, but there is much more that is not. [Personally, I guess I just have to develop the habit of reaching for ripgrep or Emacs helm in my local clone of the nix repos, rather than web search engines, and just accept that the documentation is the source.]
I see Nix as a crucial tool for taming complexity … unfortunately it’s failing miserably at taming its own complexity.
I would like to contribute to mitigating the situation, but it’s difficult to see the best approach, or even an adequate one.
Bah, I’ve written too much already, so I’ll stop here.