| 28 Jun 2023 |
 sterni | * An important argument against dynamicism for me is that it'd be okay for <nixpkgs/lib>, but as soon as you have anything in pkgs proper that's to be documented you'll suffer. | 21:35:56 |
 pennae | exactly, all of that. which is why we would need to develop very strong conventions for what is and isn't a doc comment, a documented item, etc before moving it into nix. whether it's ever moved is going to be up in the air regardless, and in the interim nixdoc-like solutions are kind of the only option anyway | 21:37:40 |
| pennae | and they do work well enough with some outside input for categorization and namespacing | 21:38:09 |
| pennae | if we converge on something that covers a sufficient number of cases we can start thinking about formalizing the rules applied at that point and putting them into nix, before that it's all just daydreams | 21:38:57 |
| sterni | that's also true the RFC has a big risk in the sense that it'll make whatever it prescribes eternal | 22:19:30 |
| pennae | codifying what is a doc comment and what isn't would be a welcome first step in any case, even if it ends there for a while. nixdoc has to hack around that not being well-defined quite a bit today to not pick up a lot of garbage as accidental doc comments :< | 22:21:16 |
| sterni | but nixpkgs & nixdoc could also do that provisionally | 22:23:10 |
| sterni | it's only a treewide commit away | 22:23:17 |
| pennae | we've had our share of treewide commits breaking new truths tbh xD | 22:24:03 |
| sterni | this is the way | 23:10:05 |
| pennae | if you want to have a go, please do! :) | 23:18:52 |
| pennae | hopefully nixdoc#40 makes it in soon so we can fully remove docbook from the nixpkgs manual, after that there's so much opportunity for improvement | 23:20:16 |
| 29 Jun 2023 |
 asymmetric | Hey, will miss this meeting too unfortunately, sorry for the streak of no-shows, hopefully should end in the next couple of weeks.
The little work I’ve done was reviewing nixdoc. I’ll get to my open PRs on nix.dev asap, but if I’m a blocker, feel free to use your best judgement and merge ahead.
See you soon! | 13:08:58 |
| asymmetric | * Hey, will miss this meeting too unfortunately, sorry for the streak of no-shows, hopefully should end in the next couple of weeks.
The little work I’ve done was reviewing nixdoc PRs. I’ll get to my open PRs on nix.dev asap, but if I’m a blocker, feel free to use your best judgement and merge ahead.
See you soon! | 14:12:44 |
 fricklerhandwerk | In reply to @asymmetric:matrix.dapp.org.uk
Hey, will miss this meeting too unfortunately, sorry for the streak of no-shows, hopefully should end in the next couple of weeks.
The little work I’ve done was reviewing nixdoc PRs. I’ll get to my open PRs on nix.dev asap, but if I’m a blocker, feel free to use your best judgement and merge ahead.
See you soon! Thanks for the update. | 16:24:01 |
| fricklerhandwerk | And again, thanks everyone on the docs and learning journey team. It doesn’t always feel like it on the inside, and it’s not always visible on the outside, but we have taken up enormous momentum. While we’re still have many discussions around finding the right approach and aligning our views, all of you are getting awesome things done, and we’re clearly transitioning into the “performing” phase.
The last few sessions in particular were extraordinarily productive. We’re doing reviews, make decisions, merge changes, and I see a lot of major improvements for user and contributor experience on the horizon.
Don’t get me wrong, it will still take months until everything gets noticeably smoother. But I’m genuinely amazed how we managed to get rolling with a couple of hours a week from everyone. | 16:30:32 |
| pennae | wild idea for the manuals: let's enforce uuids as ids for sections. namespacing of section ids is constantly subverted, and the ids don't convey much useful information anyway | 16:37:54 |
 Robert Hensing (roberth) | they make link targets readable, which is nicer for readers who share links, and also lets us spot a link target copy paste mistake | 16:45:39 |
| Robert Hensing (roberth) | similar reason as for the store path name, although that does always include an opaque identifier as well | 16:46:31 |
| pennae | are link targets read or their contents very often? (don't actually know.) | 16:47:15 |
| Robert Hensing (roberth) | often enough to warrant readability I think. I can't quantify it, but I don't think we need to | 16:48:24 |
| pennae | then maybe we should add a uuid or something else guaranteed to be unique somewhere | 16:49:22 |
| pennae | because currently we have eg a #summary id buried deep in the emscripten docs, and that's just the first example we picked from grep | 16:49:50 |
| Robert Hensing (roberth) | that one will make sense once we have separate pages, fwiw | 16:50:39 |
| Robert Hensing (roberth) | unless it's buried really very deep I guess | 16:50:58 |
| pennae | nope, ids must be unique within te entire manual | 16:51:01 |
| Robert Hensing (roberth) | well that's an artificial restriction then | 16:51:16 |
| pennae | kind of. otherwise we won't be able to [](#link) them without having to duplicate knowledge of where they are | 16:51:33 |
| Robert Hensing (roberth) | most documentation systems do need the location to be part of the identifier, so it'd be a bit weird not to do that | 16:52:41 |
| pennae | it definitely was not an artificial restriction in docbook, and for maintainability's sake we're very opposed to dropping it | 16:52:47 |
