Documentation Team: Flattening the learning curve

Documentation has always been a sore point for Nix, and the 2022 community survey results clearly show demand for improvement.

Documentation, Documentation, Documentation

Documentation (once again) came up universally across almost all
respondents. Key asks in this area revolved around three aspects -
onboarding, unblocking and centralization.

After talking to many people in the past two months, collecting ideas, evidence, and experience reports, I am more than pleased to announce the Nix documentation team.

Motivation

To finally 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 appears that, so far, no one really had the time or resources required 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.

Goals

  • ease Nix learning, increase onboarding success and user retention
  • improve organization of Nix knowledge
  • lead, guide, and support community efforts

Members

Responsibilities

Team

Ordered by priority:

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

Meeting protocol

The team holds bi-weekly meetings on Thursdays 17:30-18:30 (Europe/Berlin):

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:

  • set meeting agendas on the team’s GitHub project board from issues and pull requests
    • pull requests have priority, invite authors to the meetings
    • annotate estimated discussion time for each agenda item, it should be followed
  • post meeting protocols on the Discourse documentation category
    • add notes to the respective issue or pull request as a comment
      • prepare notes collaboratively, e.g. in a HackMD scratchpad

Meeting notes should contain:

  • date of meeting
  • list of attendees
  • results and links to GitHub comments for agenda item.

Contributing

If you want to help immediately, please see How to contribute to documentation.

Funding

This effort is sponsored by Tweag. @fricklerhandwerk will dedicate at least 15h/w until at least 2022-10-31 towards improving Nix documentation.

40 Likes

Excellent initiative !

1 Like

Any easy way for the wider community to help pick up some of the work here?

Probably covered under

lead, guide, and support community efforts

But I’d love to know if ideas are already floating about :slight_smile:

4 Likes

I’d love to help where possible too! :grin:

3 Likes

Much appreciated. Proceed with our support.

1 Like

Oh! This is a good news!
I’ll try my best to contribute :slight_smile:

2 Likes

I’m keen on contributing (although likely need to be directed)!

2 Likes

(post deleted by author)

3 Likes
Hosted by Flying Circus.