For my part, I am mainly interested in the process of developing a system config from scratch. My current config works and is pretty solid, but it’s built up on a bunch of ideas and structures that aren’t mine. I stole useful looking stuff from a bunch of other configs and sort of just jammed it all together until it did the stuff I wanted. This got me over part of the learning curve, but it leaves me in the awkward position of basically understanding the components, but not really being able to explain the “why” of all those choices.
For instance, I’d love to replace my Emacs overlay with emacs-overlay or rework my Haskell overlay to use haskell.nix. I think I know enough to do the former with some thought, but I have no idea if it’s sensible or even possible to use haskell.nix for a system-wide GHC or if it’s really just for projects, and I don’t know where to look to determine that.
I decided to just start reading the manuals and the pills end to end and taking notes to start tying ideas together, but the primary target of the Nix and nixpkgs manuals definitely appears to be people writing packages. This is fine and sensible, but it leaves me a bit adrift in answering the question “how do I, starting from nothing, write a quality system config that I can version control?”
The extra sticky bit is that I primarily use Darwin, so most of the NixOS documentation that might go toward answering this question is of varying usefulness. Most blog posts are about how to package such and such type of software or a recapitulation of the “how to package GNU hello” exercise, which tells me little about how to actually configure my machine the way I want it.
All of this is to say, I would be extremely interested in seeing (and even helping to write) a “Nix book” that isn’t just a manual.
Example: This is a really slick config, with a really straightforward installation and support for multiple machines and all that cool stuff. But! I have no idea what the assumptions made in this config are, what structural choices are good or just interesting, how I could write my own config like this other than copying it and tweaking. It even installs nix-darwin as part of its setup, which would remove one more manual step from applying my config on a new machine.
What is the gap in my knowledge that lets me read this config, basically understand what it’s doing, but not be at all certain where to start to make my own?
Parts of these could (and perhaps should) be addressed in the documentation of the projects themselves, but some kind of unified “Configure your machine with Nix” or even just a “Nix config cookbook” would be huge for me (and, again, I’d be happy to help). Figuring out and documenting these patterns centrally may also encourage their conversion to modules, so that users can say “yes, I want to interact with x in this way, so I just import the module and set some variables” or “no, I want to use this differently, but now I have the mental tools to write my own module to manage this”.
From a consumer perspective, it’s also a whole lot easier for me to pitch Nix to my team if I can say “just read this book and you’ll know a bunch of things you need to know” rather than “go read the manual to learn the vocabulary, now go read these 15 blog posts, but also ignore about a third of that content because Nix and nixpkgs have improved a bunch in the last year”.
To draw an analogy, there are a handful of books on how to use any given Linux build system, and a dozen “how to use Linux to do stuff” books. On the other hand, there a dozen books worth of content on the Nix build system, but only a handful of non-source-code resources for “how to use Nix to do stuff” (where “stuff” is “anything but building packages”).
