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.
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: Nix post-build hooks · 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.
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.
(lead) @fricklerhandwerk: Already on the website, effective leader
@pennae: Privately confirmed that they don’t want to be active at the moment