- Team details
- Past meeting notes
- Attendees: @fricklerhandwerk @xin @brianmcgee @pstn @totoroot @asymmetric @infinisil @henrik-ch @pennae
- Notes by: @infinisil @asymmetric
Agenda
- more introductions (5 min)
- add members to the team (5 min)
- organise working groups for the mid-term goals
- @olaf will present the GSoD project draft
Notes
- Question: Can we take notes as well or is @infinisil just taking notes?
- Answer: Yes please take notes as well! This is a collaborative proccess.
Introductions
- @asymmetric, @brianmcgee, @totoroot are here for the first time
Team membership
-
@fricklerhandwerk: Call for maintainers in search for people to take responsibility. Please start immediately, but there’s no process at the moment.
- If you’re interested, add yourself to https://github.com/NixOS/nix.dev/tree/master/maintainers#members in a PR
- @fricklerhandwerk will add those people to the GitHub team
- Good for notifications, increasing team visibility/transparency and knowing who’s doing what
Working groups
We want to establish working groups to use the full team meetings optimally and still make progress what we set out to do.
Learning journey working group
@zmitchell: Created a PR to establish a learning journey working group:
- problem: documentation is spread across several blog posts, where it bitrots
- First priority: Establish structure for documentation, giving people a place where to publish content
-
@fricklerhandwerk: Missing is when the meeting happens
- @zmitchell: Idea is to establish group first, then agree on times, probably meet every 2 weeks
- @fricklerhandwerk: Recommend meeting weekly for a couple weeks initially
-
@fricklerhandwerk: How long do you expect it to take for results to manifest?
-
@zmitchell: Can probably decide the structure in the first meeting, bring it to the larger docs team. One week turn-around between the two groups
- Setting standards could also be done in the first meeting. Establishing tooling and workflows might take longer.
- Long-term project: Migrating the existing docs
- Never-ending project: Encourage people to contribute to docs at exact places in nix.dev
- @fricklerhandwerk: Don’t go too much into setting rules at first, start with content work quickly (i.e. outline, texts), then figure out standards over time
-
@zmitchell: Can probably decide the structure in the first meeting, bring it to the larger docs team. One week turn-around between the two groups
-
@asymmetric: What’s the difference between that working group and the docs team?
-
@zmitchell: Docs team has different priorities: Docs itself, the infrastructure, generating manpages. These aren’t about the learning journey specifically.
- The working group is mainly about new users, onboarding is the focus, present the documentation in an intuitive way.
- There is a lot of overlap.
- @fricklerhandwerk: Point is to figure out how to teach Nix
-
@zmitchell: Docs team has different priorities: Docs itself, the infrastructure, generating manpages. These aren’t about the learning journey specifically.
Technical infrastructure
-
@pennae: Technical challenges mostly solved for markdown rendering
- left to do is library function rendering. nixdoc has a PR for markdown.
- @infinisil: @ryantm has a PR to Nixpkgs using markdown rendering
-
@fricklerhandwerk: There’s a bunch of different tooling around. nix.dev is currently hosted by @domenkozar. Should possibly migrating the infra be part of the scope?
- @pennae: Can’t handle all of that at first. Nixpkgs is the largest part, if it works for Nixpkgs it should work for Nix too.
-
@fricklerhandwerk: How to distribute work well, do you need help with that?
-
@pennae: nixdoc PR could use an update
- @infinisil: I have another PR to nixdoc (GitHub - nix-community/nixdoc: Tool to generate documentation for Nix library functions [maintainer=@infinisil]), I could help out
-
@fricklerhandwerk: Is @tazjin maintaining nixdoc?
- @infinisil: My PR hasn’t been looked at
- @brianmcgee: I’ve pinged @tazjin in the #tvl IRC, I’ll report back if they respond
-
@pennae: nixdoc PR could use an update
-
@olaf: Much of that has been discussed on Matrix. Could be done without a regular team meeting.
-
@fricklerhandwerk: Yes, create issues and put them on the project board
- Please add yourself to the team, I’ll hand out write permissions
- @pstn: I’ll add myself
- @henrik-ch: Same
-
@fricklerhandwerk: Yes, create issues and put them on the project board
-
Question: Who’s part of the group?
- @pennae: So far there’s no formal group, though some people working on the topic (@ncfavier and @jtojnar have done most of the reviews, @pennae most of coding)
- @fricklerhandwerk: How about just writing down those names so people know who to ask without digging through PRs and Discourse threads? @hsjobeki may be interested as well
- @pennae: Not sure, probably not
Intellectual history
-
@fricklerhandwerk: multiple people interested in working on explanation-style documentation (less technical)
- Two aspects:
- Intellectual History: Telling why Nix (and the tools around it) exists and how it came to be
- From first principles explanation: What Nix Pills and some other resources do.
- Somewhat related is what some refer to as “developer stories”, examples:
- Some fundamental concepts are hard to grasp without preperation and many users report benefiting from that type of documentation a lot.
- Could do explanation without history, but it’s tied to it.
- Also history is very engaging, and empathic understanding helps with learning concepts
- There is some overlap with Marketing topics, but Intellectual History should probably be done by the docs team.
- @pxc and @wiseh also interested
- PR to set up the WG soon to follow
- Two aspects:
Google Season of Docs
-
@olaf presents Google Season of Docs project draft:
- Draft: add draft for Google Season of Docs project proposal by fricklerhandwerk · Pull Request #471 · NixOS/nix.dev · GitHub
- High-level summary: focus on an initial segment of the learning journey and make that sweet
- Points we aren’t focusing on, but use as a basis for our work:
- evaluating user stories
- surveying documentation
- Focus on two points to work on:
- Rewrite reference docs
- Takes a lot of effort, but important for tutorials
- Also important for making docs being easy to work on for the future
- Write tutorials
- Also want to focus on this because it has a more clear (new) user impact
- Rewrite reference docs
- Infrastructure is not the focus of GSoD only (500EUR per volunteer)
- Next steps: Clean up the document and put it into shape for submission
-
@fricklerhandwerk: Looking for feedback
-
@zmitchell: Are items on scope all things that will be submitted, or are we picking only some?
- @olaf: Focus is reference and tutorials. The user stories and surveying docs is material we use along the way. The points should get more concrete
-
@zmitchell: So these 4 are a process, not separate points?
- @fricklerhandwerk: Should include very specific which things to work on, limit it to something doable
- @olaf: soft maximum for a project is 15000 USD (500 USD for a volunter for support technical/organisational etc.)
-
@fricklerhandwerk: For reference, the Nix language tutorial would easily translate to 5000EUR all things considered (depending on average level of income in your location)
- we can hope to get more efficient with better preparation, the gained experience, and professional support if we get it
-
@zmitchell: Are items on scope all things that will be submitted, or are we picking only some?
- @fricklerhandwerk Let’s align on scope and structure with the learning journey working group