| 11 Jan 2024 |
 @bzzm3r:matrix.org | * I would like it if you could include me in the conversation with asymmetric. But this is a request, not a demand. | 20:46:30 |
| 12 Jan 2024 |
 @9999years:matrix.org | In reply to @bzzm3r:matrix.org
no. should we not value user feedback from people who found the docs so alienating they left nix entirely? this dismissive and condescending approach to anyone who points out deficiencies with the nix ecosystem is exactly why so many people view nix as fundamentally insular and user-hostile | 00:20:48 |
| @9999years:matrix.org | In reply to @mcdonc:matrix.org
you know, i submitted a pr a while back to the nixpkgs docs... and i attended a docs meeting in jitsi... and i volunteered to help.. but i'm starting to have second thoughts i've heard this one before ... every time someone explains that they've been driven out of the nix community due to perceived hostility there's a lot of "we're here to listen and learn" but nothing ever seems to change | 00:31:56 |
 @qyriad:matrix.org | In reply to @9999years:matrix.org
I read the entire nix docs but I think it's the kind of documentation that's only useful if you already kind of get what's going on. It feels like you have to gather the knowledge from various random blogs. Last time I checked there surprisingly was not a single book which covers nix. I feel like a comprehensive book which teaches nix from the ground up and explains all the different ways of using nix would really help me and I would purchase such a book without hesitation if it existed.
still lots of work to do with the nix docs
https://news.ycombinator.com/item?id=38930947
Last time I checked there surprisingly was not a single book which covers nix. I feel like a comprehensive book which teaches nix from the ground up and explains all the different ways of using nix would really help me and I would purchase such a book without hesitation if it existed.
There really does need to be a document you can read cover to cover to understand the Nix ecosystem. Nix itself, Nixpkgs, and NixOS modules can't really be understood independently in any kind of useful way. Obviously it can't cover the entire API surface of Nixpkgs, but programming books don't cover the entire API surface of the standard library either — but they should teach you enough to be able to read std docs and — critically — read and understand source code in the ecosystem!
| 00:48:01 |
| @qyriad:matrix.org | In reply to @asymmetric:matrix.dapp.org.uk
feel free to share what your experience has been like, i'm sure we can learn from it. either here or in private if you prefer I can't speak for Chris McDonough, but I can't imagine this conversation inspires much faith in this Nix community's friendliness. | 00:52:11 |
| @9999years:matrix.org | In reply to @qyriad:matrix.org
Last time I checked there surprisingly was not a single book which covers nix. I feel like a comprehensive book which teaches nix from the ground up and explains all the different ways of using nix would really help me and I would purchase such a book without hesitation if it existed.
There really does need to be a document you can read cover to cover to understand the Nix ecosystem. Nix itself, Nixpkgs, and NixOS modules can't really be understood independently in any kind of useful way. Obviously it can't cover the entire API surface of Nixpkgs, but programming books don't cover the entire API surface of the standard library either — but they should teach you enough to be able to read std docs and — critically — read and understand source code in the ecosystem!
the fact that the nix docs, the nixpkgs docs, and the nixos docs are not allowed to refer to concepts from their siblings is a big part of this -- it would be quite nice, for instance, if the nix manual explained that derivations are packages, as was proposed here https://github.com/NixOS/nix/pull/9378#discussion_r1401478906 | 01:02:17 |
| @9999years:matrix.org | this is the sort of connective tissue that's missing -- all the information is there, but users have a hard time finding it, and part of the reason for that is there's so many places to look for any given piece of information | 01:02:58 |
 infinisil | 9999years: I think it's more that Nix is the underlying foundation, Nixpkgs is based on Nix, and NixOS is based on Nixpkgs | 01:10:06 |
| infinisil | So the dependency chain is strictly NixOS -> Nixpkgs -> Nix. There's no arrows back | 01:11:00 |
| infinisil | So generally I don't think there should be explanations of concepts making use of such back-arrows.
However, in order to find information, I'd be in favor of a mechanism that automatically inserts back-links in all documentation | 01:12:06 |
| infinisil | So if Nixpkgs links from stdenv.mkDerivation's docs to the ones for derivation, in the derivation docs you'd see a little "this page is linked to from the stdenv.mkDerivation docs" link | 01:12:48 |
| @qyriad:matrix.org | In reply to @infinisil:matrix.org
9999years: I think it's more that Nix is the underlying foundation, Nixpkgs is based on Nix, and NixOS is based on Nixpkgs this helps you understand how the Nix ecosystem is implemented, not how it's used or how and why it's useful | 01:13:33 |
| @9999years:matrix.org | i mean it would certainly be useful to say in the nix manual "derivation is used to implement higher-level packaging tools like stdenv.mkDerivation in nixpkgs" | 01:13:47 |
| @9999years:matrix.org | having recently helped several beginners get started with nix i can confirm this sort of thing trips new users up pretty consistently | 01:14:18 |
| infinisil | 9999years: Maybe yeah, but also, I've thought multiple times before to just ditch builtins.derivation and use builtins.strictDerivation instead in Nixpkgs, which would then outdate the docs on the Nix side | 01:15:08 |
| infinisil | The Nix codebase generally really doesn't know how it's used. And there could be various Nixpkgs versions that are each implemented differently | 01:16:11 |
| @9999years:matrix.org | yeah i mean, this is one of the issues with nix's docs -- nixpkgs and nix are deeply intertwined, but they can't be versioned together, even trivial stuff like lib | 01:16:47 |
| infinisil | I think such automated back-links might be a good compromise tbh | 01:17:01 |
| infinisil | Needs a unified docs building infrastructure though | 01:17:11 |
| @9999years:matrix.org | yeah automated back-links would be great. i still think additional human-written context would be useful but back-links would be a fantastic start | 01:17:28 |
| @9999years:matrix.org | (and lots more backlinks) | 01:17:42 |
| @qyriad:matrix.org | agreed | 01:17:50 |
| @qyriad:matrix.org | automated backlinks would be great, but why should we compromise on providing clear, understandable information in documentation? | 01:18:18 |
| infinisil | Wrong docs are imo worse than missing docs | 01:18:35 |
| @9999years:matrix.org | e.g. the stdenv.mkDerivation docs don't actually link to builtins.derivation or explain that mkDerivation is a wrapper around builtins.derivation and not a separate thing
https://nixos.org/manual/nixpkgs/unstable/#sec-using-stdenv | 01:18:48 |
| infinisil | And if we write information about Nixpkgs in Nix, that can easily become wrong | 01:18:53 |
| @qyriad:matrix.org | In reply to @9999years:matrix.org
e.g. the stdenv.mkDerivation docs don't actually link to builtins.derivation or explain that mkDerivation is a wrapper around builtins.derivation and not a separate thing
https://nixos.org/manual/nixpkgs/unstable/#sec-using-stdenv oh wow it doesn't even do that? o.o | 01:19:03 |
| @9999years:matrix.org | i'm not saying we should have a ton of nixpkgs docs, but we should feel comfortable referring to high-level nixpkgs concepts that are unlikely to change (like mkDerivation, the override and overlay systems, etc.) | 01:19:33 |
| infinisil | I'd be okay with that yeah | 01:19:51 |
| @9999years:matrix.org | explaining that things like overlays are just implemented as regular nix expressions would help users understand that they're not magical features or hard-coded into nix | 01:20:09 |
