| 12 Jan 2024 |
 @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 |
| @9999years:matrix.org | but right now you basically just have to ask an expert or read the source code, and the nixpkgs source code for the stdenv stuff, overlays, overrides, and so on is gnarly especially for beginners | 01:20:33 |
| @qyriad:matrix.org | In reply to @infinisil:matrix.org
And if we write information about Nixpkgs in Nix, that can easily become wrong vice versa is also true. certainly what's cross-explained can be limited, but something as simple as "derivation is used to implement higher-level packaging tools like stdenv.mkDerivation in Nixpkgs. See link for more information" | 01:20:38 |
| infinisil | In reply to @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 Reminds me of https://github.com/NixOS/nixpkgs/pull/248220 and https://github.com/NixOS/nixpkgs/pull/255132 | 01:20:58 |
| @qyriad:matrix.org | In reply to @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 this would be fantastic | 01:21:54 |
| @9999years:matrix.org | In reply to @infinisil:matrix.org
Reminds me of https://github.com/NixOS/nixpkgs/pull/248220 and https://github.com/NixOS/nixpkgs/pull/255132 those PRs look great! what's blocking them from being merged? | 01:22:16 |
| @9999years:matrix.org | i see this 'perfect is the enemy of the good' stuff a lot with nix docs, where PRs that improve docs are rejected or bikeshed because they're not perfect. but they don't need to be perfect, they just need to be better than they were before | 01:22:46 |
| @qyriad:matrix.org | In reply to @infinisil:matrix.org
And if we write information about Nixpkgs in Nix, that can easily become wrong * vice versa is also true. certainly what's cross-explained can be limited, but something as simple as "derivation is used to implement higher-level packaging tools like stdenv.mkDerivation in Nixpkgs. See link for more information" would help a lot for little overhead | 01:22:47 |
| @qyriad:matrix.org | especially when the state of the docs is so poor | 01:23:09 |
| infinisil | Yeah.. | 01:23:11 |
| infinisil | So the first one is indeed ready, I'll just merge. People can make follow-up PRs to improve on it | 01:23:27 |
| infinisil | The second one is very incomplete though | 01:23:35 |
| infinisil | Needs more work | 01:23:39 |
| infinisil | And merged :) https://github.com/NixOS/nixpkgs/pull/248220#issuecomment-1888257490 | 01:26:03 |
