SIG: Documentation meeting on 2024-06-08
Attendees:
- @coded (Samuel Shuert)
- @minion (Skyler Grey)
- @liketechnik (Florian)
- @8bitbuddhist
Agenda
- @coded: Document importTOML with examples
- @minion: that was adding examples to importTOML and importJSON for @isabel
- @coded: there’s a pull request, waiting on infinisil for approval
- @minion: pkgs.writeScript & associated writers
- @minion: the writers are documented in the manual, I don’t think we can get noogle to read it…
- @coded: maybe we should try to make something that combines this?
- @minion: that sounds challenging to pull things together… I’m not sure how worth it it’d be at this point?
- @coded: we could maybe read some manual links for some of these things? It should be possible to do…
- @minion: how valuable is that compared to how challenging, though?
- @coded: yea, sounds quite challenging
- @8bitbuddhist: I like this as a long-term idea, but maybe not as a priority
- @coded: Maybe we can compile a resources page in the meantime?
- @minion: this exists on the wiki: Resources | Auxolotl Wiki
@dfh: treefmt template/module work- Next week, not present (ill?) today
- @isabel, @liketechnik: What else should we document from lib (Things to document - HedgeDoc)
- @liketechnik: We made a list of things that have no docs, missing docs, are different functions/aliases, etc. at the notes list
- @liketechnik: We haven’t discussed which have high priority now
- @liketechnik: For some things, there’s maybe not much benefit to documenting some things (lib.types) …
- @coded: Maybe worth having an example, but a novel of prose is probably not worth it
- @minion: There is a bit in the manual about types …
- @liketechnik: Some things are documented in the manual, but they aren’t documented with the code and there’s not necessarily a way to see specific parts … maybe it’s a low priority?
- @minion: Ok, maybe we need to expand our Resources page to have more details on where to go for different “If I’m looking for help with lib, I go to Noogle; if I’m looking for help with writers, I go to the manual”
- @liketechnik: I experience discoverability of what lib contains is really bad, I was shocked that some things existed
- @liketechnik: e.g. generators
- @liketechnik: e.g. docker tools
- @coded: maybe we could have a search engine for this?
- @minion: I wonder if people would know what to search…
- @8bitbuddhist: maybe we could have a list of high-level “what does this bit of lib do”? Then again, I don’t know how big lib is…
- @minion: I’ve previously used Nix (builtins) & Nixpkgs (lib) Functions, it can show you all the things in lib…
- @coded: Maybe adding the above link to the resources page is a good idea
- @8bitbuddhist: maybe summarizing the submodules (e.g. lib.strings is about string manipulation, lib.trivial is…)
- @coded: community templates
- @minion: Migration to Forgejo
@dfh: “How to document your SIG/Committee” guide- Next week, not present (ill?) today
- @minion: resources page expansion
- @minion: I’ve added descriptions to some of the items as well as done some page reorganization like moving tutorials up top.
- @liketechnik: Yea this looks good.
Action items
- @minion, @coded: Move wiki & docs to forgejo
- @minion, @coded: Forgejo CI (buildbot)
- @8bitbuddhist: Summarize lib sub
- @liketechnik: Where to find docs for specific pieces (expand resources page? new page?)
Standing reminders
- Next meeting will be at the same time next week!
