|
|
||
|---|---|---|
| .. | ||
| this-month-in-nix-docs | ||
| documentation-project-2023.md | ||
| documentation-survey.md | ||
| google-season-of-docs-2024.md | ||
| information-flow.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 organisation of Nix 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
Current members are listed on the website, and can be pinged using the GitHub team @NixOS/documentation-team.
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
Office hours
The team currently holds office hours every work day. Check the NixOS calendar for details.
These meetings are free for everyone to join. Contact @fricklerhandwerk to get a calendar invitation for reminders and updates.
Meeting links
Meeting protocol
The purpose of the meetings is to
- work on documentation together
- coordinate efforts
- share knowledge
- make strategic decisions
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 a meeting agenda 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 the 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
- @zmitchell led the Learning Journey Working Group from 2023-03 to 2023-08, sponsored by flox
- @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
History
Many thanks to past members, who helped make Nix documentation what it is today:
-
@brianmcgee was part of the team from 2023-03 to 2023-10 and contributed to the Learning Journey Working Group effort.
-
@zmitchell led the Learning Journey Working Group from 2023-03 to 2023-08 that added a number of tutorials. He published regular updates on developments in documentation in that period.
-
@Mic92 was a founding member and part of the team from 2022-05 to 2023-01. Jörg had written a great deal of documentation on the NixOS Wiki, and shared his experience to set a direction for the documentation team.
-
@domenkozar was a founding member and part of the team from 2022-05 to 2023-01. Domen originally started nix.dev, wrote many basic tutorials, and funded editorial work through Cachix. He helped bootstrap the documentation team, handed out permissions, and advised us on many aspects. Domen donated nix.dev to the NixOS Foundation 2023-07.