| 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 |
| John Ericson | Anyways I am first going to try to finish the concrete spec info | 13:12:58 |
| John Ericson | but then I will try to make the abstract part less philosphical | 13:13:16 |
| 9 Aug 2022 |
| tpw_rules | https://github.com/NixOS/nix/issues/6623 | 02:13:29 |
| tpw_rules | * is there an alternate branch or something with the new nix documentation rendered? | 02:13:44 |
| tpw_rules | i saw it was commented out from the official docs shortly after it was merged | 02:13:51 |
 asymmetric | should we remove experimental commands from the stable nix manual? | 10:12:16 |
| asymmetric | e.g. https://nixos.org/manual/nix/stable/advanced-topics/post-build-hook.html?highlight=sign#implementing-the-build-hook uses nix store sign | 10:12:28 |
|  Solène Rapenne (she/her) changed their display name from Solène (she/her) to Solène Rapenne (she/her). | 15:14:25 |
|  Bryan Honof joined the room. | 15:33:02 |
|  Ken Sonoda joined the room. | 16:00:11 |
| fricklerhandwerk | In reply to @asymmetric:matrix.dapp.org.uk
should we remove experimental commands from the stable nix manual? In the documentation team so far we have consensus that, yes, we should not assume or nudge people to use what is not stable. But we also want to document flakes as good as we can, ideally to be ready in sync with a stable release. | 16:14:04 |
| Ken Sonoda set a profile picture. | 16:24:10 |
| 10 Aug 2022 |
|  Flávio Martins Prado joined the room. | 05:45:16 |
| Flávio Martins Prado | Hi, just noted that the link to matrix on the manual preface is broken | 05:45:54 |
| Flávio Martins Prado | should a report be open or one just correct on nixpkgs directly? | 05:46:24 |
