| 8 Mar 2024 |
 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 |
| infinisil | (I guess I'm also on the docs team, my opinion mainly comes from consensus there) | 21:04:48 |
| @jade_:matrix.org | it's dissolved? news to me, we should write that in the topic and on the website :P | 21:04:51 |
| Qyriad | In reply to@jade_:matrix.org
yeah, it's reference level though, which is the difficulty imo It definitely is, yeah. We try to think of it as describing the roles that things fill, at least as the primary focus. "makeScoope is used to create a package set with these properties" is easier to think about than trying to reverse engineer all the pre- and post- assumptions of a poorly documented behavior | 21:04:54 |
| infinisil | In short:
- The manuals are for reference docs only
- nix.dev is for all tutorials and guides
- CONTRIBUTING.md and README.md's throughout the source code are for docs exclusive to contributing
| 21:05:27 |
| @jade_:matrix.org | the last category is extremely unfit for purpose imo: there is no way of searching all of them cleanly | 21:06:05 |
| Qyriad | It definitely is, yeah. We try to think of it as describing the roles that things fill, at least as the primary focus. "makeScoope is used in these places to create a package set with these properties" is easier to think about than trying to reverse engineer all the pre- and post- assumptions of a poorly documented behavior | 21:06:07 |
| infinisil | Agreed, I'd be in favor of making the contributor docs use some better rendering | 21:06:28 |
