Minutes from SIG: Documentation on 2024-05-25



  • Approval/revision of agenda
  • @isabel: Nixpkgs lib documentation
    • @isabel: pkgs.writeScript, etc. are poorly documented
    • @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?
    • @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
    • 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!


  • 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!

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

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!