| 6 Aug 2022 |
 tpw_rules | okay, that makes sense | 18:04:54 |
 John Ericson | :) | 18:05:03 |
| tpw_rules | might be rushing things in my head a bit | 18:05:05 |
| John Ericson | everyone wants to write tutorials because that is where the need is | 18:05:24 |
| John Ericson | but I think the "yak shave" of a good complete reference will pay off pretty quickly | 18:05:39 |
| John Ericson | even though it does feel like a distraction up front | 18:05:49 |
| tpw_rules | yes, that's why i was excited about fricklerhandwerk's just-merged commit. but i feel like the ordering of the reference material is important too | 18:06:26 |
| tpw_rules | maybe it's because i and all my colleagues are engineers. i don't care so much or know about FP theory. i just want a nice list of the words nix uses and how they relate | 18:07:12 |
| tpw_rules | but on the other hand, a lot of the existing nix material feels like what you said: "a big bag of special cases with the underlying theme left as an exercise to the reader" | 18:07:44 |
| tpw_rules | (and tooling...) | 18:07:48 |
| tpw_rules | is that just the nature of nix? should the Grand Unified Theory be at the end of the reference? | 18:09:00 |
| John Ericson | oh oops | 20:21:07 |
| John Ericson | more grand unified theory sure, and more trying to get upstream stuff to think about us so there is less "no one anticipated this" friction | 20:21:34 |
|  yuu changed their display name from yuu[m] to yuu. | 20:34:47 |
|  wentasah joined the room. | 22:14:56 |
| 7 Aug 2022 |
| tpw_rules | what i'm saying is i wonder if the reference should be introduced in more practical terms first. | 00:20:18 |
| tpw_rules | i.e. swap the concrete model and the abstract model in the toc | 00:20:43 |
|  cnn_npc joined the room. | 08:57:56 |
|  夜坂雅 | Yorusaka Miyabi joined the room. | 09:03:57 |
| 8 Aug 2022 |
 fricklerhandwerk | 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.
- it's a trade-off between brevity/clarity, length, and completeness
- it's a trade-off in terms of invested effort
- 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.
| 10:42:20 |
| John Ericson | fricklerhandwerk: So for me the downsides are clear but narrow | 12:24:52 |
| John Ericson |
it's a trade-off between brevity/clarity, length, and completeness
I reference needs to be complete
| 12:25:02 |
| John Ericson | *
it's a trade-off between brevity/clarity, length, and completeness
A reference needs to be complete
| 12:25:07 |
| John Ericson | Trading completeness for anything else in a reference I think is basically pandering | 12:25:25 |
| John Ericson | the other documentation quadrants handle brevity and clarity | 12:25:40 |
| John Ericson | Of course, this is an argument for just folding the abstract stuff in the concrete sections too, because | 12:26:07 |
| John Ericson | * Of course, this is an argument for just folding the abstract stuff in the concrete sections too :) because there is no hard reason it can't just be longer sections with more information in a reference | 12:26:42 |
| John Ericson |
but it will not be helpful for the vast majority of software developers who just want do get their job done - our targeted audience!
| 12:27:19 |
| John Ericson | *
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
| 12:27:44 |
| John Ericson |
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
| 12:29:01 |
