| 29 Jun 2023 |
 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 |
| fricklerhandwerk | Here's another piece for the survey regarding contributor workflow: https://floxdev.com/blog/nixpkgs-contribution | 22:37:45 |
| 30 Jun 2023 |
 sterni | why can’t nobody at flox proofread such articles (if they are even wise to publish in that context)? Couple of inaccuracies and multiple things that are wrong presented as facts. | 07:36:05 |
|  jakob joined the room. | 08:33:28 |
|  ruby changed their profile picture. | 14:02:47 |
 Sandro 🐧 | FYI https://github.com/NixOS/nixpkgs/pull/240754 | 16:15:47 |
| sterni | pennae: maybe every md file for the manual could have an unique prefix assigned to it (e.g. haskell- for haskell.section.md). The md toolchain would then prefix every reference in the markdown file with that unless it is already prefixed. That would ensure unique anchors as long as the prefixes are unique.
Problem is of course that anchors would be changed, maybe we'd need to generously whitelist existing ones.
| 16:16:14 |
| sterni | * pennae: maybe every md file for the manual could have an unique prefix assigned to it (e.g. haskell- for haskell.section.md). The md toolchain would then prefix every reference in the markdown file with that unless it is already prefixed. That would ensure unique anchors as long as the prefixes are unique.
Problem is of course that anchors would be changed, maybe we'd need to generously whitelist existing ones. Still seems better than uuids.
Personally I'd also just be fine with a linter that checks for link uniqueness
| 16:16:37 |
| pennae | that's an option too, though we'd have to include the path of the file from the doc root instead of just the file name itself (and that can get pretty long) | 16:42:55 |
| pennae | nrd already checks for uniqueness and throws an error on duplicates, but that's a pretty bad experience. and the anchors that are likely to be problematic are exactly the ones that don't convey meaning | 16:43:37 |
