| 28 Jun 2023 |
 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 |
| Robert Hensing (roberth) | yeah it's yet another project | 16:53:04 |
| pennae | In reply to @roberthensing:matrix.org
most documentation systems do need the location to be part of the identifier, so it'd be a bit weird not to do that arguably that just makes the location part of the id, which does not solve the underlying problem :/ | 16:53:49 |
| pennae | the mismatch from input files to output files that we've now inherited from docbook complicates this even more | 16:55:37 |
 alejandrosame | 
Download Screenshot from 2023-06-29 18-05-37.png | 17:11:12 |
| alejandrosame | Sharing a screenshot of the WIP work on the nixpkgs manual Python section. | 17:12:09 |
