Minutes from SIG: Documentation on 2024-05-25

coded · May 25, 2024, 5:44pm

Attendees:

@minion: Skyler Grey
@coded: Samuel Shuert
@liketechnik: Florian Warzecha
@nova
@isabel: Isabel Roses

Agenda

Approval/revision of agenda
@isabel: Nixpkgs lib documentation
- @isabel: pkgs.writeScript, etc. are poorly documented
  - https://noogle.dev/f/pkgs/writeScript: “No reference documentation found yet.”
- @isabel: lib.packagesFromDirectoryRecursive is a little hard to understand at first glance…
- @skyler: so, you’re interested in us documenting these lib things that don’t have documentation yet
- @skyler: what do you think the best format should be?
  - @isabel: I don’t much care
  - @isabel: we could host our own noogle? Perhaps wiki pages would be better?
  - @coded: I wonder about [problems with] adding nixpkgs-specific documentation to our wiki rather than upstream?
    - @minion: I can see some stuff diverging… maybe this isn’t an issue?
    - @isabel: we plan on pulling in upstream lib for stdlib, and having our own auxlib ontop (GitHub - auxolotl/lib: System-agnostic library functions used by auxolotl repositories)
    - @coded: then I think it makes sense to contribute upstream
    - @minion: I would prefer to avoid fracturing nix docs even further
      - @minion: it could be worth having something like noogle?
      - @isabel: @jakehamilton wonders about changing the format of doc comments … [conversation for another day?]
- @minion: what isn’t documented properly?
  - @isabel: importTOML doesn’t have examples
    - @isabel: I & a friend previously thought that maybe was equivalent to readFile…
    - @isabel: …but actually it imports the TOML content
    - @minion: so an example would rectify this, it would be excellent to have an example there!
  - @isabel: writers don’t have documentation
Wiki pages
- Templates
  - @coded: we’ve made a template! onboarding for sigs/committees
  - @coded: we think the best way is to assign specific pages/templates to specific people, rather than expecting that “someone” will work on them
  - @minion: shall we get a list of templates/pages that we want to make?
    - wiki-templates/community/… needs more things
- WikiJS navigation
  - @coded: Sidebar hider plugin causes the sidebar to hide permanently at some widths
  - @minion: if the plugin is causing breakages, probably we should remove it
Docs-site
- Canonical URLs
  - done (thanks @8bitbuddhist)!
- CI (linked to below topic)
  - waiting on forgejo
Forgejo status update
- Auxolotl Forgejo
- there’s a bug with importing pull requests properly … we’ve filed this with forgejo devs and are looking at fixing/working around it!
Adding topics to the agenda
- We need more involvement if people want topics throughout the week – or we need to add these things!

Decisions

CI (Hold off on till Forgejo change-over)

Action items

@minion: Remove the dynamic sidebar plugin from the wiki
@coded: Document importTOML with examples
@minion: Document pkgs.writeScript & associated writers in a way noogle can understand
@isabel & @liketechnik: Go through and start a list of undocumented lib (pkgs & pure) items (Missing Lib Docs - HedgeDoc)
@coded: Create templates for other common community pages (welcome page, communication, task management)
@coded & @minion: Update formatting tools page - adding treefmt
@liketechnik: wiki page for list of documentation pages (Noogle, nix wiki, etc.)!

Standing reminders

Next meeting will be at the same time next week!

srtcd424 · May 31, 2024, 8:15pm

is it too soon to change the link on https://aux.computer ?

minion · May 31, 2024, 8:18pm

So, this hasn’t been announced officially yet… but we did get the bug fixed so there’s minimal infrastructure work before we can fully migrate over (mostly CI, etc.)

Feel free to sign up and/or send us a message if you’d like to help!