2022-06-15 Documentation team meeting notes #1

Attendees: @mat @fricklerhandwerk @Infinisil @edolstra @Mic92
Notes: @fricklerhandwerk

Agenda (60 min)

  • agree on goals and structure (25 min)
    • proposal:
      • goals:
        • improve organization of Nix knowledge
        • set up and maintain central learning resource
        • lead and guide community efforts
          • goals and roadmap
          • quality standards
          • tough decisions
          • dirty work
      • regular meetings
        • weekly for the first month
        • bi-weekly after that
      • regular reports
        • monthly
      • initial editorial team
        • Valentin Gagarin
          • lead until 2022-10-31
        • Domen KoĹľar
        • Jörg Thalheim
  • agree on schedule and scope (10 min)
  • further considerations
    • Rok: delineate responsibilities with marketing team (10 min)
      • where does marketing and documentation overlap and meet?
      • report on experience leading a team
    • Matthias: update on Summer of Nix 2022 (10 min)
  • collect issues and topics for first meeting (5 min)

Notes

  • @fricklerhandwerk Want to find a follow-up date to have @domenkozar on board before moving on too quickly

  • @garbas

    • bi-weekly meetings worked for marketing team
    • Work is usually done by very few people
    • Liked how UX team invited people to contribute
      • Creating a PR is the ticket to join the team (temporarily)
    • The more people you have the slower you move
      • A lot of people have to be onboarded all the time
    • Uncontroversial tasks
      • Tutorial for Nix language
        • @fricklerhandwerk Domen has one in the making
        • @mat Isn’t that what we have the most of?
        • @fricklerhandwerk Goal of docs team would be to provide guidance and structure, mostly centralize existing material
  • @Mic92

    • It is fine to migrate NixOS content to central resource
    • Must be easy to edit in the new location
    • @edolstra should not replace the NixOS Wiki
      • Central resource should be curated
      • Do not expect much from documentation PRs
        • Contributions always requires guidance by maintainers
    • @mat set up different resources for different levels of quality/effort
      • Establish clear workflow/pipeline how to get material from one place to the other
  • Scope and audience

    • @garbas marketing team decided to target developers
      • Cannot serve everyone, will fail
      • Reason: even if NixOS was used by 100% of Linux users, that would still be less than 2% of software developers
        • Can still look at NixOS through development environment lens
    • @fricklerhandwerk documentation should align with marketing
      • Actually all teams should align on common goals
    • @Infinisil NixOS is integral part of Nix community
      • Don’t want to separate them out
      • @garbas nobody came up to do the work on the website
        • Problem: hard to come up with a hello-world example for NixOS
        • Also: most people don’t see distinction between Nix and NixOS
    • Flakes
      • @garbas focus on the new stuff first, in general
        • When 3.0 comes out, part of that experience should be awesome documentation
        • Set new standard in community for documentation
      • Currently we don’t mention flakes at all
        • Decide on roadmap for transition
    • @infinisil @mat Nixpkgs is the biggest problem right now, most badly documented
      • This is what you interact with all the time
      • @fricklerhandwerk nixpkgs too large to change, have to keep scope narrow
        • @mat Nothing works without commit bit
        • @infinisil distinguish between being able to review and merge
        • Goal here is to overhaul Nix learning journey
          • requires sweeping, structural change
            • Not possible with nixpkgs without commit access
              • Possibly not meaningful to attempt in the foreseeable future
            • Should focus on what we can handle immediately
  • Summer of Nix:

    • @mat how to encourage and enable contributors to get their work merged?
      • There will be large amounts of material at different levels of quality
        • How to guide that?
      • @garbas Is there a lack of leadership for that?
        • @mat Yes, no one making hard calls what to accept for which resource.
          • Need a “pressure valve” for stream of contributions
          • Biggest problem observed at Summer of Nix 2021
      • How to instruct participants?
        • People will come with their work and ask where to put it
        • @garbas Direct them to documentation team!
          • If it’s non-trivial, join meeting and discuss to get it merged
  • @mat Something like this?

  • Docs team would encourage contributors to each high-rate-of-change resource to migrate their work to a lower-rate-of-change resource

  • @mat Team needs a person with both time and commit access

    • Summer of Nix team has full control of their repositories
    • @edolstra Docs team should at least have commit bits to documentation
    • @Mic92 Arrange for nixpkgs commit bit
  • Meeting point of marketing and documentation teams:

    • @garbas Marketing goals: bring more people to Nix
      • Could meet on the “learn” page
        • Partially marketing responsibility: what goes on that page? (not detailed contents)
          • Goal: Improve retention
        • Try to get first steps right (Nix, NixOS, Nix language, different programming languages)
    • @fricklerhandwerk proposing split:
      • Marketing: retaining users after first impression
      • Documentation: learning Nix properly
  • @fricklerhandwerk Team should work completely in the open, as marketing team did

    • Will publish these notes retroactively once @domenkozar had opportunity to give input
  • 5 min over time

Action items

Write down for documentation team (see meeting #2)

  • Vision and goals
  • Responsibilities
  • Meeting structure, participation rules

Grant @fricklerhandwerk commit access

Get @fricklerhandwerk write access to NixOS calendar (done)
Draft communication hierarchy (see meeting #2)
Draft contribution guide postponed
Schedule meeting #2

  • Decide schedule
  • Decide team goals
  • Decide meeting structure
  • Decide communication hierarchy draft
  • Discuss pipeline for Summer of Nix

Decide contribution guide draft postponed

8 Likes

It would be great if markdown was used across the board. It would lower the barrier to contribute to the docs a lot.

1 Like

There are a few efforts underway, but it ebbs and flows depending on what people put attention towards.

Here are related resources buried in the depths of this forum:

1 Like