Hello Timothée & Brendan, Sorry to hear about your bad first-contribution experience, Timothée, and your poor experience as well, Brendan. It is a fact that we’re not doing great when it comes to incorporating “simple” contributions: they’re just lost in the infinite stream of contributions that go from “fix a typo” to “rewrite a subsystem”. Teams are supposed to help, and I would expect the documentation team to be proactive in this area, but there’s still work to do.
> Maybe this is a feature, not a bug, as Ludovic was saying. But in my opinion > having a community more open to "easy" > contributions (here for documentation) would be beneficial. IMHO a solution > to keep things in sync with Guix can either be by > having a small curated cookbook as it is done now, or by having more people > (i.e. people that are not yet contributing to Guix) > contribute and declare things "out of date" when it becomes out of date. > Remark that the lack of "how to" documentation was > already mentioned as one of Guix's bad side in the contributor survey > > https://guix.gnu.org/en/blog/2025/guix-user-and-contributor-survey-2024-the-results-part-1/ As I wrote, the goal is to make contributions to the Cookbook very open to contributions, with limited curation. The problem I guess is that in reality people don’t dare or feel entitled to modify it (I recently saw a blog post that really could/should have been a patch to the Cookbook) or give up after a bad experience like you. I’m not sure how to improve on this. BTW, contributions to documentation (the manual) are not easy, contrary to what one might think. It’s not immediately visible, but a lot of attention to detail went into the manual or at least parts of it: information hierarchy, choice of words, cross-references, sectioning, etc. (which of course doesn’t mean it’s perfect). It’s easy to overlook them when considering “just one small change” to a specific section. But again, this applies to the manual; the Cookbook is much more free-style. > On another note, I would also suggest that a wiki could encompass other > channels (I am thinking guix-science typically) and how > to find other channels, which is I think important. I already advised > several people, typically on reddit, on how to use external > channels and how to find them (via toys website). On the topic of finding channels, there’s Toys and there’s <https://hpc.guix.info/channels> for this specific sub-domain. But yeah, it would be nice to host a registry at guix.gnu.org. > It's like the development process is a state > machine that exists between the brains of developers, and it can be difficult > to grasp what the future plan is or if there even is one, > even after reading hundreds of emails, issues, and pull-requests . I think we need to improve on legibility. I personally like to write blog posts as a way to tell about recent developments, to connect them with earlier developments, and to give an outlook, showing that there’s a line of work and not just a bunch of independent pull requests. But perhaps we also need to document developer workflows, as you suggest, similar to what Hako did for Rust packaging: https://guix.gnu.org/cookbook/en/html_node/Packaging-Rust-Crates.html#Packaging-Rust-Crates Thanks, Ludo’.
