[lakecresva]

This was exactly my experience. They have manuals that are very comprehensive reference texts, but complete lack of structure (no types, no docstrings, no enforced conventions/standards, extremely poor discoverability) makes it a nightmare in practice.

[throwaway894345]

Right, most recently I was looking at the reference for buildGoModule, which produces two derivations--one for pulling the dependencies (e.g., go mod download) and another for building the package. Basically the idea is to avoid re-downloading dependencies if only the package's source code has changed. Anyway, buildGoModule takes a `goModHash` field (or something like that, anyway) which is supposed to be the hash of the dependencies derivation; however, it completely omits any information about how to actually get that hash (and if you think you can just build the package and get the correct hash from the error message, you're mistaken). Googling around a bit online you'll find that you can use nix-prefetch, but it appears to only work on Linux. Note that this quirk is particular to Go, but this is the same sort of thing that you run into all the time in the Nix ecosystem.

[microtonal]

and if you think you can just build the package and get the correct hash from the error message, you're mistaken

Actually, you can. In any place a SHA256 hash is required, you can put *lib.fakeSha256" (which is an all-zeros hash) and the build will fail and Nix will tell you what the correct hash is.