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

SIG: Documentation meeting on 2024-06-01



  • Lib documentation
    • @minion: pkgs.writeScript & associated writers
  • @isabel, @liketechnik: What else should we document from lib
    • Not present, carry forward to next week
  • Wiki pages
    • @minion (on behalf of @coded): community templates
    • @minion: Formatting tools (treefmt challenges)
      • @minion: we can’t enable all the formatters at once because you have to download them all…
      • @minion: …we were planning to make a module
      • @dfh: would it make sense to start treefmt with markdown + nix and then do additional things later on? do we need to cover everything from the getgo?
      • @minion: yea, that would be maybe a simpler way to start off than making a module/etc.
      • @dfh: can we set sensible defaults enabled by default?
        • @minion: I want to avoid downloading all the formatters to be able to use it, it makes more sense to me to explicitly enable used languages I think
    • @liketechnik: other documentation index
      • Looks like it’s the Resources | Auxolotl Wiki page
      • @minion: looks good to me :slight_smile:
      • @dfh Me too
      • @minion: might be nice to have some descriptions/etc.
        • @dfh: Yes, if you’re a newcomer you don’t necessarily understand all the things. If you don’t know what everything means yet it’s hard.
        • @minion: Ok, let’s look at that…
      • @dfh: can we add nixos-and-flakes.thiscute.world?
        • @minion: yes, do it!
          • @dfh: Done + Some re-ordering of topics to reflect a “learning journey” for newcomers
      • @dfh: Can/ should we add a small description for each entry that explains: what is behind the link, who should read it, what solutions can I find
  • Forgejo status update
  • Markdown dialect/extensions
    • @minion: so far, we’ve just been using “whatever wikijs does”, which is CommonMark + extensions (Markdown | Wiki.js)
      • @minion: that means that we’ve used some things which aren’t quite “standard markdown”
      • @minion: Examples would be like info blocks
      • @minion: on https://docs.auxolotl.org we use remark, it displays some stuff slightly wrong so we want to make a plugin for it
    • @dfh: I was particularly wondering if we can put a formatter into wiki.js. It feels quite weird to only enforce the formatting on direct edits to the repo
      • @minion: yea, I get that, I don’t think wiki.js has the ability to do this. We could take a look and see, but we would probably be extending wikijs
      • @minion: it’s unfortunate, if you have suggestions for alternative ways to do editing that we could control this for, I’d be interested, but I don’t want to force people to use git to edit our wiki
  • What should we do in the upcoming week?

Action items

  • @dfh: I’d like to look at treefmt stuff
  • @dfh: “How to document your SIG/Committee” guide
  • @minion: fleshing out more of the resources page
  • @minion: pkgs.writeScript & associated writers
  • @coded: community templates
  • @isabel, @liketechnik: What else should we document from lib

Standing reminders

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

Is this just for docs or for everything? If the latter I will stand down my unofficial hydra experiments, I was already coming to the conclusion that (as I was originally advised!) there might well be better options out there!

It’s the latter, but we’d be more than happy to have help/experimenting with buildbot-nix!


Is there a Git hook for GitHub Action we could use to “catch and format” changes made on the website?

Sorry, I couldn’t make it. Hopefully shall be there next week.


So we could do this, I’d be a little worried about what would happen to conflicts, since as the sync happens once every 5 minutes … possibly we could look into if the filesystem integration does a more continuous sync?