| .. | ||
| this-month-in-nix-docs | ||
| documentation-project-2023.md | ||
| documentation-survey.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
The team member list is maintained on the Nix community documentation team page.
Responsibilities
Team
Ordered by priority:
- Establish and maintain guidelines for contributing to documentation in the Nix ecosystem
- Extend and curate nix.dev as the central learning resource
- Review and merge Nix pull requests, Nixpkgs pull requests, and NixOS pull requests concerning documentation
- Keep track of Nix issues, Nixpkgs issues, and NixOS issues concerning documentation
- Maintain and develop documentation infrastructure
- Monitor the Documentation Discourse category
- Monitor the Nix* Documentation Matrix room
In addition, the team has to perform administrative tasks which it distributes across team members:
- Triage issues and pull requests
- Curate the GitHub project board
- Invite new participants
- Schedule meetings
- Moderate and keep to the schedule
- Take and publish meeting notes
- Keep team information up to date
Team members are encouraged to become maintainers and take ownership of some piece of documentation they care about. The team lead supports team members who want to take on maintainer responsibilities.
Team lead
- Set a direction and agendas
- Represent the team
- Publish announcements and reports
- Exercise elevated privileges:
- Manage permissions for the GitHub team and the GitHub project board
- Update NixOS calendar events
- Merge pull requests approved by team members
Team meetings
The team holds weekly meetings on Mondays 16:00-17:00 and Thursdays 16:00-17:00 (Europe/Berlin):
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
- share knowledge
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 discoverable and accessible, we will:
- Prepare meeting agendas in the collaborative scratchpad
- Estimate and follow estimated discussion time for each agenda item
- Pull requests have priority
- Invite authors to the meetings if possible
- Take notes in a collaborative scratchpad
- Add notes to existing issues or pull requests as a comment and link them back to the meeting notes
- Merge pull requests made on the last session
- Submit new pull requests or issues
- Post the meeting notes on the Documentation Discourse category
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.
Sponsoring
- [@fricklerhandwerk] serves as the team lead since 2023-02, sponsored by Antithesis
- [@infinisil] works on the team since 2022-11, sponsored by [Tweag]
- @lucperkins served as the team lead from 2022-11 to 2023-01, sponsored by Determinate Systems
- [@fricklerhandwerk] served as the team lead from 2022-05 to 2022-10, sponsored by [Tweag]