2022-11-03 Documentation team meeting notes #14

Attendees: @lucperkins @fricklerhandwerk @yuki_is_bored @infinisil @edolstra

Notes: @lucperkins, with help from @infinisil and others (drawn from HedgeDoc)
Agenda: Nix documentation · GitHub

  • Announcing new acting team lead. Valentin Gagarin @fricklerhandwerk from Tweag is handing the reins over to Luc Perkins @lucperkins from Determinate Systems.

  • Priorities for upcoming quarter

    • Theme: unblocking, pt. 2
    • Contributor guides
    • nixos.org
      • Easy contribution: Markdown, standard static site generator, designed for mere mortals
    • nix.dev
      • Unclear ownership
      • Making it an official source (removing opinionated bits, like avoiding with)
      • Definitive Nix community source
      • “Cookbook”-y; realizing user stories.
      • @yuki_is_bored: Sometimes reads more like a tutorial than a cookbook.
        • Separate user guides and tutorials
        • @fricklerhandwerk: eventually we should have different “books”, one for each category
      • @infinisil: Leave in opinionated bits but mark them as opinionated?
      • @fricklerhandwerk: @edolstra, how has the community previously handled similar controversial questions?
        • @edolstra: we don’t have an established process that has proven successful
          • @fricklerhandwerk: may be food for contributing guides, at the least to set expectations
            • possible recommendation to contributors: break down pull requests to changes that are unambiguously improvements
          • @lucperkins: the foundation should foster the broader discussion how to deal with substantial changes, this is out of scope for documentation
      • @lucperkins will set forth an action plan in the upcoming docs team meeting. Discussion and potential divvying up of tasks to follow.
  • Moving on to docs team agenda

Note from new team lead, @lucperkins: I’m still getting the hang of this, so bear with me for a little bit here :smile:. Many thanks to @fricklerhandwerk for his past and continued service and for a smooth transition. Looking forward to confronting the many challenges in this domain!