2023-02-09 Documentation team meeting notes #27

Attendees: @infinisil @fricklerhandwerk @yuki_is_bored @wiseh @HapticBovine

  • @infinisil: do the new attendees want to join the docs team?
    • @fricklerhandwerk: let’s exchange interests and ideas first
      • @yuki_is_bored: improve navigation, especially of the Nixpkgs manual
      • @HapticBovine: interested in products, things that make people feel good
        • reducing friction for contributors
        • working on the nixos.org website, readability, performance, SEO
          • currently trying to figure out who owns this, looks like docs team is involved
            • @fricklerhandwerk: the marketing team actually does, but it is mostly inactive currently
              • @lucperkins is working on a rewrite, we’re waiting for updates. this is going to be a big bang PR
                • @infinisil: should ask to publish the work in progress, otherwise we cannot collaborate meaningfully
                  • agreement
              • @infinisil: a rewrite is useless if it won’t get accepted
                • we should reach out to code owners, foundation board, or the community (through RFC) to make sure the change will land
      • @wiseh: happy to work on whatever problems encountered while learning NixOS
        • also concerned with overall structure of documentation
            1. The lack of a clear guide on how to get into the Nix ecosystem.
            1. The existence of package documentation in the manuals
            1. Prioritizing the creation of non-linear documentation.
  • @infinisil: let’s announce that the documentation team is looking for members
    • agreement
    • @fricklerhandwerk: should talk about ownership. we don’t have a clear owner for the NixOS manual
      • what could we do to encourage people to step up to take ownership of a piece of documentation? what would be concerns, questions?
        • @yuki_is_bored: owner should be dogfooding. I don’t use NixOS, so I wouldn’t want to own its manual
        • @HapticBovine: having no idea what I’m doing, having very specific opinions based on related experience
      • @infinisil: ideally that should be someone who is in the community for a while
        • @fricklerhandwerk: yes, but those people are mostly really busy (for good reasons)
          • we could onboard maintainers with small chunks of ownership, such as one article or section
            • agreement
            • @infinisil: the only problem is that owners should be able to merge PRs to their owned code, but nothing else.
              • there were discussions on Nixpkgs, but GitHub currently doesn’t allow this
              • it again comes down to infrastructure and organisational aspects
                • for example, the RFC process is focussed on the community, not the code owners in question
                • same for sponsoring: someone has to give a direction eventually, and give green light for treewide changes
              • @fricklerhandwerk: we could short-circuit this global problem (that the docs team cannot address anyway) by having a social contract. docs team members can get commit access to the repositories where they own code and just promise not to touch anything outside their responsibility. team leads should be responsible to check for activity and ask org owners to grant revoke permissions as needed.
  • @infinisil: we need a work meeting, like the Nix team
    • @fricklerhandwerk: agreed. we don’t really have issues to triage due to low number of contributions, but we can still use the discussion meeting to make decisions on what to focus on
  • action items:
    • get in touch with @lucperkins to publish nixos-homepage work (@fricklerhandwerk)
    • publish recruitment call on Discourse
      • Write a draft (@infinisil)
        • Find more participants for the docs team
        • Find a codeowner for nixpkgs and NixOS manuals
        • Review/edit together next time
1 Like