Minutes from SIG: Documentation meeting on 2024-06-08

SIG: Documentation meeting on 2024-06-08



  • @coded: Document importTOML with examples
  • @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?
  • @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…)
          • @minion: Yea, I think that’s quite a nice idea. Maybe we could make a wiki page this week to see how that goes?
  • @coded: community templates
    • @coded: I have started a communications template, waiting on @minion and @dfh for email. Got notice yesterday that we can use forgejo projects for project management, so I’ll be making that template soon …
  • @minion: Migration to Forgejo
    • @minion: Forgejo instance is up on https://git.auxolotl.org you are welcome to sign up from now. There’s no CI yet, @coded and I are working on setting this up still.
    • @minion: Me and @coded will be moving docs stuff over ASAP.
    • @minion: Steering Committee is going to announce this soon, by Monday.
  • @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

Standing reminders

  • Next meeting will be at the same time next week!

Apologies for not being able to make, IRL things have kept me away from the keyboard.

Hoping/ planning to have some update for this weeks meeting :crossed_fingers: