SIG: Documentation meeting on 2024-07-06
Attendees:
- @coded (Samuel Shuert)
- @dfh (Olly)
- @liketechnik (Florian)
- @jakehamilton (Jake Hamilton)
Agenda
-
Approval/Revision of Agenda
-
@dfh: “How to document your SIG/Committee” guide // @dfh: Treefmt template/module work
- @dfh: Was wondering if there was anything specific for formatting with snowfall lib.
- @jakehamilton: Yep, that would be the output builder.
- @dfh: The other thing was that I founda bunch of outdated stuff in the template repo like old links to github. I think I’ll go through and fix all those.
- @coded: That would be great.
-
@coded: Forgejo CI (Buildbot)
- @coded: started a module for it, but not yet complete. missing pieces for adding workers
- @coded: #10 - WIP: Start module for buildbot-nix - auxolotl/infra - Auxolotl Forge
-
@8bitbuddhist: Template README’s on wiki
- @coded: @8bitbuddhist hasn’t been feeling great this week but here’s an update from them.
- @8bitbuddhist: I’ve still got a couple of commits to rebase on the template, and the readme to draft up for the wiki. I also need to double-check the Gnome part of the template since some packages had their scope changed.
-
@pyrox: Nixpkgs markdown documentation generation- not here today
-
@liketechnik: Document more undocumented lib bits
- @liketechnik: didn’t have time.
-
@jakehamilton: Document labs lib
- @jakehamilton: There’s a couple levels of this. It’s mostly stable, no large fluctuations. I’d like to make it more accessible.
- @jakehamilton: The lib currently has some level of documentation on each function with type annotations or similar. Right now however it’s not particularly readable. I’d like for it to be easier for people to understand with examples and type annotations.
- @jakehamilton: Some type annotations are very specific and some could use some work.
- @coded: I can take some time this week to look through that this week.
- @jakehamilton: It’s not something that needs to be rushed. Maybe we can get a generator written?
- @coded: I know pyrox is working on a generator maybe we can wrap this into that.
- @dfh: https://diataxis.fr/ Maybe we can try and follow something like this.
- @coded: I would have take a look, but it looks promising.
- @jakehamilton: It’s a couple of different kinds of documentation.
- @jakehamilton: I think that’s a great point @dfh
- @jakehamilton: Right now we’re looking for more the reference type of docs.
- @dfh: I’m wondering if we as docs team can find some patterns in which is best to document these different views, they shouldn’t be too far apart. Maybe there’s a way to have all of it in one place.
- @coded: I think the only issue is then you end up with 90% docs and 10% code in a file.
- @jakehamilton: I think there’s a happy medium, rust does a very good job at this.
- @coded: I would have take a look, but it looks promising.
-
@jakehamilton: Thanks for working on all this stuff, it means a lot. Aux is a community project and we’re glad that you’re continuing to it.
-
@liketechnik: I’ll be absent the next two meetings
-
Any other business
Action Items
- @coded: Forgejo CI (Buildbot)
- @coded / @dfh: Look through labs lib and start docs
- @dfh: “How to document your SIG/Committee” guide
- @dfh: Treefmt template/module work
- @8bitbuddhist: Template how to’s on wiki
- @pyrox: Nixpkgs markdown documentation generation
Standing reminders
- Next meeting will be at the same time next week!