| 8 Mar 2024 |
 @jade_:matrix.org | In reply to @infinisil:matrix.org
jade_: Very recent! https://github.com/NixOS/nix.dev/pull/935 ah, but there should be reference docs for that! | 20:53:21 |
 infinisil | Yeah that too 😅 | 20:53:38 |
| infinisil | I'll take any docs at this point! | 20:53:43 |
| infinisil | jade_: Oh wait did you see https://github.com/NixOS/nixpkgs/pull/294194? | 20:54:24 |
| @jade_:matrix.org | Part of the problem is that there is some NAT responsibility here, since it is in NAT purview which one should be used, and so that guidance falls on NAT, somewhat blocking the nixpkgs-dev-guide level docs | 20:54:50 |
| @jade_:matrix.org | In reply to @infinisil:matrix.org
jade_: Oh wait did you see https://github.com/NixOS/nixpkgs/pull/294194? omg recent! | 20:54:59 |
| @jade_:matrix.org | i like that | 20:55:01 |
| @jade_:matrix.org | I can file a bug if that's helpful | 20:55:34 |
| infinisil | In reply to @jade_:matrix.org
Part of the problem is that there is some NAT responsibility here, since it is in NAT purview which one should be used, and so that guidance falls on NAT, somewhat blocking the nixpkgs-dev-guide level docs My thoughts on that is that there's a delicate balance between actually fixing the root problems and getting side-tracked | 20:55:50 |
| @jade_:matrix.org | yeah | 20:55:58 |
| infinisil | (and makeScope and co seems like a side-track to me) | 20:56:14 |
| @jade_:matrix.org | we do still have:
- busted ecosystem specific fixed points re mkDerivation
- busted ecosystem specific makeScope implementations and conventions
| 20:56:38 |
| @jade_:matrix.org | https://github.com/nixpkgs-architecture/issues/issues/21 there is this already i suppose | 20:57:21 |
 Qyriad | The Nix docs need to service people reading code as well as writing it, and if you're trying to figure out how Nixpkgs works — generally the only way to do that right now is by reading the source — you're going to encounter makeScope and friends, and they show up in a lot of critical places. | 20:57:37 |
| Qyriad | A guide on using them correctly is not particularly urgent, I agree, but right they are now confusing, which is a state to escape from | 20:58:40 |
| @jade_:matrix.org | I guess my issue with the writing of the docs is that there are multiple ways of doing it and I don't want to step on toes or reveal unknown-to-me consensus while doing it and have to rewrite what I'm doing heh. | 20:59:05 |
| Qyriad | Self-fufilling prophecy 😔 | 20:59:36 |
| @jade_:matrix.org | yeah | 20:59:39 |
| infinisil | jade_: An idea I like is to limit yourself to writing something for e.g. 1 hour. Stop after that and ask for feedback before continuing | 21:00:20 |
| infinisil | This makes it more iterative but still keeps it asynchronous | 21:00:56 |
| @jade_:matrix.org | another side thing is, we have:
- guide level user docs for nixpkgs (nix.dev)
- reference level user/developer docs for nixpkgs (manual)
and then we have ...... sorta:
- one very busy page of guide-level developer docs that people read once (CONTRIBUTING.md)
so it's not clear where to put our norms?
| 21:01:03 |
| @jade_:matrix.org | Thinking about https://rustc-dev-guide.rust-lang.org/ | 21:01:42 |
| infinisil | I'd like for these to all be rendered in a more unified way, but I think the distinction makes sense to a degree | 21:02:01 |
| Qyriad | Imo the Nixpkgs manual is actually a good place for "this is how the sausage gets made" in absence of a more dedicated place | 21:02:06 |
| infinisil | I'd like more automatic cross-links | 21:02:07 |
| @jade_:matrix.org | In reply to @qyriad:katesiria.org
Imo the Nixpkgs manual is actually a good place for "this is how the sausage gets made" in absence of a more dedicated place yeah, it's reference level though, which is the difficulty imo | 21:02:19 |
| infinisil | This is becoming a documentation discussion, how about moving to #docs:nixos.org? | 21:02:53 |
| @jade_:matrix.org | sure, but it is somewhat a question of the architecture team having a place to write | 21:03:10 |
| infinisil | The architecture team never really tried to give a direction for these things, and it's also dissolved now.
| 21:04:07 |
| infinisil | I do have an opinion on this though :) | 21:04:29 |
