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)


  • @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
  • @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


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