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
- Valentin Gagarin
- goals:
- proposal:
- 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)
- Rok: delineate responsibilities with marketing team (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
-
- 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?
- It’s not on nixos.org
- @fricklerhandwerk Goal of docs team would be to provide guidance and structure, mostly centralize existing material
- Tutorial for Nix language
-
- 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
- @edolstra @fricklerhandwerk We have to educate them
- 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
-
@garbas focus on the new stuff first, in general
-
@infinisil @mat Nixpkgs is the biggest problem right now, most badly documented
- This is what you interact with all the time
-
@fricklerhandwerk
nixpkgstoo 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
- Not possible with nixpkgs without commit access
- requires sweeping, structural change
-
@garbas marketing team decided to target developers
-
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
-
@mat Yes, no one making hard calls what to accept for which resource.
- 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
- There will be large amounts of material at different levels of quality
-
@mat how to encourage and enable contributors to get their work 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
-
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)
- Partially marketing responsibility: what goes on that page? (not detailed contents)
- Could meet on the “learn” page
-
@fricklerhandwerk proposing split:
- Marketing: retaining users after first impression
- Documentation: learning Nix properly
-
@garbas Marketing goals: bring more people to Nix
-
@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
- @edolstra Nix
- @domenkozar Nixpkgs
- @garbas Nix website
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