John Ericson: We've extensively talked about this in the course of developing the architecture docs. I have a clear opinion on this, but it's kind of hard to formulate briefly.

1. it's a trade-off between brevity/clarity, length, and completeness
2. it's a trade-off in terms of invested effort
3. the ultimate goal in this scope is to help people understand Nix enough to make best use of it

writing even the part that got merged and commented out again took weeks of wall-clock time, and many full work days user time. I think we struck a very good balance so far, because the contents are very specific to Nix while still introducing an idea of the overarching theme, and still got it brief enough for people to consume in an afternoon, and precise enough to get back for details.

I agree that there is a meta-topic about content-addressing, immutability, and theory of computaton, but I deem it very much out of scope for Nix documentation. It is not the place to introduce or explain any of that. If there were a reference on that, we could gladly mention it as an alternative venue to understanding Nix, but it will not be helpful for the vast majority of software developers who just want do get their job done - our targeted audience! Just as I think it was (and still is, my PR to change that is yet to be merged) a big mistake trying to explain Nix in terms of Haskell to an audience that on average struggles to understand Haskell to an even greater extent. It may be true that Nix appears like a special case of something more general to Haskellers, it is a minority that does not need help anyway.

So, I would prefer to stick to Nix specifics and only keep hinting at the bigger picture, because Nix works right now.

it's a trade-off between brevity/clarity, length, and completeness

I reference needs to be complete

it's a trade-off between brevity/clarity, length, and completeness

A reference needs to be complete

but it will not be helpful for the vast majority of software developers who just want do get their job done - our targeted audience!

but it will not be helpful for the vast majority of software developers who just want do get their job done - our targeted audience!

The target audience a reference for me is people who don't just care about getting a job done, but want to understand it more completely

I agree that there is a meta-topic about content-addressing, immutability, and theory of computaton, but I deem it very much out of scope for Nix documentation.

It's not supposed to be a theory of things in general, it is supposed to be a theory of just Nix. I can fold together every abstract--concrete pair, but I do need to say what all the various types of store objects, drvs, etc. have in common at some point