Minutes from SIG: Documentation on 2024-06-22



  • Approval/Revision of Agenda
  • Introductions (Pyrox)
    • @pyrox: I’ve been a somewhat active contributer in nixpkgs. I’m in college for cybersecurity. I’m in Aux because I feel it’s a place to remodel nix into something maybe more modern.
    • @coded: I’m coded, I’m a leader of the docs group … working on getting the documentation to be more usable, particularly interested in beginner documentation.
    • @liketechnik: I’m Florian, I’ve used nix for ~3 years, and I’m in SIG: Docs because I’ve realized documentation is an important part of software, and it’s important to get it right for nix.
    • @8bitbuddhist: I’m Andre, I’m on the SIG: Docs team, I’ve written some stuff for new users. I’m somewhat new to the ecosystem. Right now my main focus is on getting a new user template working.
    • @minion: I’m Skyler, I’m the other leader of the docs group. I’m also in various other places in aux (steering, infra…), I’m looking to make Docs run smoothly, I want to make sure Aux is a great place for beginners to help them find what they need easily.
  • @minion / @coded: Forgejo CI (Buildbot)
    • @minion: We’ve had some experiments going on in the matrix…
    • @minion: We’ll look at getting something temporary up by next week, and once our infra is up we’ll move everything over to something more permanent.
  • @liketechnik: Where to find docs for specific pieces
  • @8bitbuddhist: New user guide on the wiki & expansion on the template
    • @8bitbuddhist: Still working on the new user template. Most of the system stuff is already there.
      • For context: it’s hard to get a more “traditional” system up and running, this is to help you quickly bootstrap a system with some reasonable defaults … hoping that should allow getting up something reasonable quickly
    • @8bitbuddhist: Right now I feel it’s in a pretty good spot. Maybe we should look at merging it in!
    • @8bitbuddhist: Looking at making the default lix.
  • @dfh: “How to document your SIG/Committee” guide
    • Not here this week
  • @dfh: Treefmt template/module work
    • Not here this week
  • @pyrox: The nixpgks wiki is one giant page and that’s not a good format in my opinion. Use the comments above each function to generate an mdBook like thing.
    • @minion: That seems like a really good idea. How can we help?
      • @pyrox: I was just going to start hacking on a prototype, might take a few weeks. Just to prove the idea is possible
      • @minion: I’d be happy to help with that.
      • @coded: +1
    • @coded: Not all the docs for everything is formatted correctly or right above the code.
    • @minion: We’ve looked at noogle a bit and we’ve put some docs into nixpkgs lib. But it’s very inconsistent.
    • @pyrox: Yea I want to take a look at maybe combining the ref manual and the code comments.
    • @minion: Maybe look at how the code links to the manual and parse those and cut up the manual as needed. It’s not a straightforward problem, sounds great if we can do it though!
    • @minion: Any ways we can help that isn’t code related?
  • @liketechnik: Been in my mind, I’ve accidently stumbled upon an issue on the old github. When do we start documenting the modules stuff in Auxolotl/labs? I know we don’t want to start with it to early in case the architecture changes ago because it quickly gets more difficult to document the further it progresses
    • @coded: Might be good to contact Jake to see if it’s going to continue to drastically change.
    • @minion: Yea the stuff is still very experimental so at the moment maybe our time is best spent documenting other more concrete items.
    • @minion: Labs has this thing in the readme called “experiment phases”. They include “idea” “iteration” “proposal” and “adoption”. We may want to start documenting when it gets to mid to late iteration when it gets stable enough.
    • @coded: Good to work out with Jake and other members to flesh out when to start would be best?
    • @minion: @8bitbuddhist what would be the best time to start on that?
    • @8bitbuddhist: I think it’s best to wait until something is actually useable to start documenting it.
    • @minion: Then for now we will wait until a project is at it’s proposal page to start documenting, of course if whoever is working on the project does documentation that’s always welcome.

Action Items

Standing reminders

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