2023-02-23 Documentation team meeting notes #29

Attendees: @olaf @fricklerhandwerk @pennae @stefanschroeder (later: @infinisil)


Postponed to next time

  • get back to a board-based workflow
  • collect major goals as GitHub issues and bake them into the team handbook

State of NixOS manual

  • @pennae: only worked on rendering, not contents
    • NixOS release notes editing process has been working quite well
      • may be enough to have that if we don’t manage to find a full maintainer
  • @olaf: there is a lot to do, and a proper rendering infrastructure would help to make changes
    • nix.dev proved to be a good starting point to find smaller projects
    • wouldn’t know how to get a PR to the NixOS manual reviewed
    • if we followed Diátaxis, we’d have to reduce the amount of material in the manual
      • but cannot just remove it, but have to find a new place and then remove it from the manual
  • @fricklerhandwerk: agree with everything above
    • would like to get this team to focus on recruiting maintainers, and editorial and technical leads to work on the issues that are most pressing
      • most importantly we need someone for each manual to know the whole thing and have a vision, and spend the time to draft a migration path from here to there such that anyone can pick up chunks of work according to their capabilities

Drafting the announcement

  • Documentation Team Nominations - HedgeDoc
  • (some debate on who exactly to address)
    • @fricklerhandwerk: we need both code owners as well as regular contributors
    • @olaf: yes, there should be a distinct group of team members other contributors can rely on to make decisions and create a coherent vision
    • @infinisil: not the last announcement, should start with owners
    • agreement
  • (worked on clarifying team’s near-term goals)
  • @fricklerhandwerk will make a review pass and together with @infinisil make the draft ready for publishing


  • @stefanschroeder: observed a quite high-level discussion on vision, and it’s good it’s happening
    • given the amount of documentation out there, expected the team would have a more established, agenda-based, itemised workflow
      • @fricklerhandwerk: we’ll get back to that once we get back on track organisationally
        • separating administrative and productive tasks makes sense, and having two sessions per week would be ideal for that
    • propose to do research on existing materials and improve manuals and tutorials from there
      • @fricklerhandwerk: yes, prior art here
        • last year we only managed to agree on a very shallow ad-hoc roadmap, but we got things done
        • hope to return to building and following a more deliberate roadmap and quickly delve into making it a reality
  • @pennae: can only contribute technically, but not take ownership of contents
    • @fricklerhandwerk: thank you so much for your work, your technical contributions are invaluable
      • hope we can continue collaborating async