2023-10-19 Documentation team meeting notes #87


  • Curate the doc team members and update it on nixos.org
    • Who should be in the docs team? Let’s double check with the nix.dev list and recent work and meetings
      • :white_check_mark: (lead) @fricklerhandwerk: Already on the website, effective leader
      • :white_check_mark: @infinisil: Already on the website
      • :x: @pennae: Privately confirmed that they don’t want to be active at the moment
      • :white_check_mark: @olaf: Recently active on nix.dev
      • :white_check_mark: @henrik-ch: Always active
      • :white_check_mark: @zmitchell: Active, but recently passed on the lead of the Learning Journey WG
      • :x: @pstn: Not active
      • :x: @Jeremiahs: Not active recently
      • :white_check_mark: @asymmetric: Active, maintaining nix-doc
      • :white_check_mark: @wamirez: Active, getting sponsored
      • :white_check_mark: @proofconstruction: Newly leading the Learning Journey WG, busy but active
      • :white_check_mark: @roberth: Busy but active, getting sponsored
      • :white_check_mark: @alejandrosame: Active, working on Python docs, getting sponsored
      • :x: @stefanschroeder: Not often active
      • :x: @brianmcgee: Left the Learning Journey WG recently
      • :white_check_mark: @yuki_is_bored: Occasionally active
      • :x: @erooke: Not active, listed as part of the Learning Journey WG
      • :x: @JillThornhill: Previously worked on docs survey, not active recently
      • :x: @j-k: Not active
    • Let’s also not have descriptions for the members, these could get outdated, we don’t want to maintain that
    • @henrik-ch: Will make a PR for this, copying the above list to ping everybody
      • Will have to confirm discourse vs github nicks
        • Figure out @wamirez’s Discourse nick
      • Put in the PR description that we should wait for like a week before merging, so that people have the chance to confirm/complain
        • Draft PR so it can’t be merged too early
      • Another PR afterwards to remove the list from nix.dev

I’d like to contribute more. What’s blocking me:

  • the documentation team’s call often overlaps with my work hours.
  • I am not really an expert on anything Nix related. Even the “good first issues” are outlandish. They either require deep knowledge (making them not really good first issues), access rights that I don’t have, or are vague and need more discussion.
    What I can do:
  • I can proofread or review tutorials, documentation with a fresh eye being a Nix beginner.
  • I have 25+y experience w/ Linux.

I see, that’s good feedback, thanks for wanting to help out!

For now I think one of the easiest ways to help out is to follow the nix.dev repo and review PRs.

For me too ,but that’s not really a problem. Maybe have a look at previous posts to the see what is the focus of discussion.

I don’t really understand what accress rights you are missing. Prs and reviews should be possible.

Maybe also join the matrix channel to get direction what to work on that’s of interest to you.

Thank you for taking the time to answer, olaf. ok, access rights wasn’t really what I meant. I absolutely do not expect to have any extended permissions. It’s more like that I don’t even know where to provide the PR’s or reviews. Who would receive the PR? Who do I put in to be notified? On GH, nixpkgs has ~5000 open PRs, how does this work? How is it supposed to work? Nix.dev now has the fancy Suggest an edit label, that’s nice. But if I wanted to suggest an edit on the manuals on nixos.org, where would I go? Let’s take another “first good issue” as an example, the first that came up in my list: Migrate `post-build-hook` guide to nix.dev · Issue #463 · NixOS/nix.dev · GitHub. It’s about maintain different types of documentation the appropriate contexts. But it doesn’t specifically talk about which documentation exactly should go exactly where. How would a newbie know, making this a good first issue?

Re. Matrix. Perhaps I’ll do that. I am not familiar with Matrix. When I search for “Nixos Matrix”, the first match is the NixOS-Wiki. The wiki-page doesn’t explain what the NixOS community is using Matrix for. What is “the matrix channel”? It doesn’t explain where to sign up, what the features are, what the implications are, what channels exist (does Matrix have channels? I don’t know.) etc. When I open the Matrix page, I am required to pick a client. My first choice would be Thunderbird. When I open the Chat tab in Thunderbird, I have to enter a Matrix-username and a Matrix-servername. I have neither. There is no rationale. There is Nix-code on that wiki-page, but no instructions to perform even the most basic setup! This is symptomatic for a lot of Nix documentation. It’s great for people who already know exactly what they are looking for.

1 Like

i also think that migrating information is more difficult then it initially appears. I think the easiest way to contribute to documentation (for me at least) is to take a topic that interests you and fix the documentation of that topic.
the link to the matrix channel can be found here: Documentation Team | Nix & NixOS

Thanks @StefanSchroeder for this detailed report on where you’re struggling to contribute. This is very valuable feedback that’s – I think – non-obvious for people who have been around long enough, and aligns pretty much with what I’ve been saying last year about making contributions easier: often people struggle on their way to the first contribution, and we have barely any way to notice this.

And that’s a shame, because GitHub, plain text editing, the Nix language, and the astronomical complexity of the open source ecosystem make for enough of a learning curve already.

About the issues with Matrix specifically: please check Nix Community | Nix & NixOS for whether it better explains what you had trouble with. We can fix that text based on your input. We can’t really do much about the Wiki‘s visibility in search engine results apart from improving nixos.org and nix.dev and reworking Wiki articles to point people to authoritative and well-maintained sources.

1 Like