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

minion · June 1, 2024, 6:20pm

SIG: Documentation meeting on 2024-06-01

Attendees:

@dfh (Olly)
@minion (Skyler)

Agenda

Lib documentation
- @minion: pkgs.writeScript & associated writers
  - @minion: I’m in the process of getting noogle working, etc. so that I can test some of this locally
  - @dfh: Noogle is the search for lib, right?
  - @minion: yes, https://noogle.dev/
~~@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: Coded has made Onboarding | Auxolotl Wiki
  - @minion: he plans to continue filling in more community templates over the next weeks … it’s helpful to have examples so we can make more of these which fit what we want easily when SIGs/Committees make pages of these types
  - @dfh: Would it make sense to start with a “How to document your SIG/Committee” guide under the templates?
    - @dfh: like an instruction manual for the templates
    - @minion: Yea, that sounds quite good, I’d be happy to see this at https://wiki.auxolotl.org/en/wiki-templates/community or https://wiki.auxolotl.org/en/wiki-templates!
      - @dfh: Maybe it makes more sense on the wiki-templates level
      - @minion: Is that a thing you could do?
- @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?
    - @dfh: can we have a flake template with the formatters?
      - @minion: yea, that sounds great! GitHub - auxolotl/templates: Nix templates for quickly bootstrapping a system with Auxpkgs might be the place for this!
      - @minion: e.g. we’ve got a “c” template, we should have treefmt there
  - @minion: yea, that would be maybe a simpler way to start off than making a module/etc.
    - @dfh: Can we have module & template?
    - @minion: Yes
  - @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
      - @dfh: Agreed.
- @liketechnik: other documentation index
  - Looks like it’s the Resources | Auxolotl Wiki page
  - @minion: looks good to me
  - @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
    - @minion: Yes plz
Forgejo status update
- @minion: some stuff exists, https://git.auxolotl.org
- @minion: myself and coded are working on CI before everything is migrated, we want to set up buildbot-nix (GitHub - Mic92/buildbot-nix: A nixos module to make buildbot a proper Nix-CI.). We probably will migrate some repositories over early to test everything, infra is already on there but we haven’t yet archived the old repo
- @dfh: why buildbot-nix
  - @minion: it has great community support and looks like it will work great with forgejo!
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
```
> 
{.is-info}
```
  - @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!

srtcd424 · June 1, 2024, 7:21pm

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!

minion · June 1, 2024, 7:25pm

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

8bitbuddhist · June 2, 2024, 3:41pm

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

isabel · June 2, 2024, 4:20pm

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

minion · June 2, 2024, 4:22pm

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?