|
|
||
|---|---|---|
| .. | ||
| this-month-in-nix-docs | ||
| working_groups/learning_journey | ||
| documentation-project-2023.md | ||
| how-to-contribute-to-documentation.md | ||
| README.md | ||
| responsibilities.md | ||
Nix documentation team
The Nix documentation team was formed to flatten the infamous learning curve.
Goals
- ease learning, increase onboarding success and user retention
- improve organization of knowledge
- lead, guide, and support related community efforts
Motivation
To improve the state of affairs with Nix onboarding and documentation, we have to tackle some big issues and work through many small ones: implement structural changes after gathering the necessary social support; fix numerous little problems and help people get their contributions merged.
It requires significant time or resources to do this consistently. The team is built around that limitation, and therefore organized as a praxicracy: you are in charge if and only if you get the work done.
The team’s reason to exist is to make that principle discoverable and reproducible by laying groundwork and setting examples.
Members
-
Valentin Gagarin (@fricklerhandwerk)
Nix documentarian, Tweag
-
Silvan Mosberger (@infinisil)
Nixpkgs maintainer, Tweag
-
@pennae (they/them)
NixOS and Nixpkgs contributors
-
Olaf Hochherz (GitHub: @olafklingt, Discourse: @olaf)
-
Henrik Karlsson (@henrik-ch)
-
Zach Mitchell (GitHub: @zmitchell)
-
Jeremiah Secrist (GitHub: @JeremiahSecrist, Discourse: @Jeremiahs, Matrix: @jeremiahs:matrix.org)
-
asymmetric (he/him)
Working Groups
Responsibilities
Team
Ordered by priority:
- establish and maintain guidelines for contributing to documentation
- extend and curate nix.dev as the central learning resource – long-term vision: The Nix Book
- review and merge Nix pull requests and Nixpkgs and NixOS pull requests concerning documentation
- keep track of Nix issues and Nixpkgs and NixOS issues concerning documentation
- monitor the Documentation Discourse category
- monitor the Nix* Documentation Matrix room
- monitor changes to the NixOS Wiki
Team lead
- represent the team:
- publish announcements and reports
- keep team information up to date
- lead team meetings:
- set the agenda
- invite participants
- announce meetings on the calendar
- moderate and keep schedule
- take and publish notes
- support maintainers
- assist new maintainers to get commit access (NixOS GitHub organisation owners can hand out permissions)
Team meetings
The team holds weekly meetings. For an up-to-date schedule, see:
These meetings are free for everyone to join. Contact @fricklerhandwerk to get a calendar invitation.
Meeting links
Meeting protocol
The purpose of the meetings is to
- make strategic decisions
- coordinate efforts
- exchange experience and insights.
As the Nix community is distributed globally, available time for synchronous communication is highly limited and therefore very valuable. Writing is still the primary medium of communication.
To keep discussions highly focused and make their results accessible, we will:
- prepare meeting agendas as pull requests on the nix.dev repository
- pull requests have priority, invite authors to the meetings
- annotate estimated discussion time for each agenda item, it should be followed
- prepare notes collaboratively in a HedgeDoc scratchpad
- merge pull requests made on the last session
- submit new pull requests or issues
- add notes to existing issues or pull requests as a comment
- post the meeting protocol on the Documentation Discourse category
- update calendar invitations
Meeting notes should contain:
- date of meeting
- list of attendees
- results and links to GitHub issues and pull requests for each agenda item
Contributing
If you want to help immediately, please see How to contribute to documentation.
Funding
This effort was sponsored by [Determinate Systems]. [@lucperkins] served as the team lead until 2023-01.
This effort was sponsored by Tweag. @fricklerhandwerk served as the team lead from 2022-05 to 2022-10.