2022-10-22 Documentation team meeting notes #12 - NixCon edition

Development Documentation
1

Attendees: @fricklerhandwerk @Mic92 @LucPerkins @brainrake @john-rodewald @yuki_is_bored @milibopp @zupo

Notes: @milibopp @fricklerhandwerk

Motto of the day: It’s documentation all the way down

Brainstorming pain points

Categorize and find patterns

  • discoverability
    • nixos.org navigation, layout
    • structure of documentation (separation of concerns)
    • search tooling, quality
    • interlinking
  • contribution process
    • where to put what - also structure above
    • ease of contribution, technically and cognitively
  • guidance
    • strategic decisions for documentation…
    • make obvious what are official sources
    • learning strategy
      • examples
      • best practices
      • what’s useful to know when

Sort out priorities

Screenshot 2022-10-22 at 16.38.46
Screenshot 2022-10-22 at 16.38.461215×564 67.9 KB

  • Expectations for documentation team lead

    • organize biweekly meetings
    • review
    • ask annoying questions
    • figure out what to work on next
    • delegate prioritized work items
    • maintain working relationship with important Nix people
    • compile list of people responsible for certain parts of the Nix ecosystem
    • maintain team handbook
    • centralize team efforts into repository

  • How to improve a contribution guide

    • get someone to try to contribute
    • watch everything they do and take notes
    • review notes, find pain points, create issues
    • fix at least one issue
    • edit contribution guide
    • rinse and repeat

Pick a goal for the next 3 months

From looking at the graph and where most arrows lead to, we define the following goals:

  1. The roles and responsibilities for maintainers of documentation in the Nix ecosystem are well-defined.

  2. The process of becoming a maintainer of documentation in the Nix ecosystem is well-defined.

Break down tasks

  • create overview of what is where

  • define a central location where the docs team is working

    • proposal:
      • what we’ve been talking about or doing: Discourse
      • results of what we’ve done: pull requests on GitHub

  • refine collaboration process

    • discussion should happen on pull requests directly
    • meeting agendas a pull requests
    • how to subscribe to Nixpkgs notification effectively
    • give advice on how to word issue titles and descriptions
    • how to subscribe to Discourse categories effectively
    • how to deal with Matrix
    • where to ask questions (Discourse), where to place proposals (Pull Request)
    • protocol:
      • merge pull request with agenda for current meeting
      • merge pull requests made on last session
      • …
      • submit pull request(s) with meeting results
      • post links to submitted pull requests on Discourse
      • update calendar/invitations

  • team lead responsibility

    • get write access to NixOS calendar
    • remove double book keeping on team info
    • get rid of project board, it doesn’t really work
    • provide list of contacts
      • determine where to put contacts list
      • can leverage CODEOWNERS on NixOS/nixpkgs
        • introduce CODEOWNERS on NixOS/nix
        • introduce CODEOWNERS on NixOS/nix.dev
    • communicate to team members what’s going on outside the team
    • monitor all the other team’s activities (read reports)
    • ensure that for each maintainer responsibility there is a guide how carry it out
    • …

  • maintainer handbook: I have an hour, how can I use that effectively?

    • how to turn questions into issues, how to turn issues into pull requests
    • how to keep track of work in progress
    • how and when to say no
      • when to close an issue or pull request
        • is the issue still valid or has it been fixed already
        • how to replicate issues
      • what if you don’t have time at the moment
        • proposal: answer that until X date there is no chance it will be even looked at
        • what if you don’t know when you will have time again
        • what if you’re not qualified to address the issue or pull request
      • how to escalate issues
    • when and how to veto changes
    • how to triage issues
    • how to leave the team
    • how to make pull requests
      • always use your private fork

  • maintainer responsibilities:

    • monitor GitHub notifications, Discourse and Matrix
      • have an entry in CODEOWNERS
        • free choice, but recommendation: pick one small thing (e.g. some manual sections, some tutorials) and that only
        • get merge access to the respective repository (required for CODEOWNERS)
      • refine: which categories/channels
    • be responsive to @-mentions on Matrix, Discourse, GitHub
      • refine: target response time
    • guide potential contributors from discourse questions to writing issues to making pull requests
      • reserve time for reviews
      • only pick up subjects that fall within what’s in your CODEOWNERS entry
    • you’re reponsible for everything you merge and have to follow up on regressions
    • subscribe to external resources that relate to your area of responsibility
      • e.g. documentation on flakes: be aware of support status or timeline to stabilization

Assign responsibilities

6 Likes