2023-03-14 Documentation team meeting notes #32

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

Team membership

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
  • @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

Technical infrastructure

Intellectual history

  • @fricklerhandwerk: multiple people interested in working on explanation-style documentation (less technical)
    • Two aspects:
      1. Intellectual History: Telling why Nix (and the tools around it) exists and how it came to be
      2. From first principles explanation: What Nix Pills and some other resources do.
    • 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

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
    • 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
  • @fricklerhandwerk Let’s align on scope and structure with the learning journey working group
1 Like

Who wants to help maintain nixdoc?

@ryantm I might be interested!

Hosted by Flying Circus.