(fricklerhandwerk I am purposefully choosing to write this here, rather than through an issue, because I would prefer if this were ephemeral. If you think it's okay to make it more permanent, let me know and I'll shift it to an issue.)

I'm sort of willing to take on work that I am pointed to.

But that motivation is not as high as it used to be, because:

(laziness.0) as I learn Nix, I become less interested in documenting it. I have a workflow, and I have made painful, but necessary, progress in shedding my fear of just looking at the source code. (There, I very much appreciate the doc strings that do exist, when they exist; but I consider them to be random gifts rather than something to expect.)

As an example, a task that is on my todo is to convert [this nix.dev page on the module system] into one that uses OpenStreetMap instead of the Google Maps API. But, I've been finding it hard to spend time on that, because I'm not sure why I should care. I went through the tutorial ultimately without actually running the code, and got what I needed out of it. So...why go back?

(A counterargument would be this, which I completely agree with, but would beg for nuance on.)

(sisyphean.0, laziness.1) I appreciate Johannes Kirschbauer @hsjobeki's work greatly, it is awesome, and I'm inclined to contribute, but...it feels quite futile. Once we are able to parse doc comments, well...then what?

Comparing with Rust (as has happened many times in the conversation above) is difficult for Nix, because Rust's dev tools (including doc generation) are enabled by its type system, which allow for nice things like, for example, automated hyperlinking (between documentation, and between docs and source) or structured documentation generation.

This reduces documentation burden for writers, to the point where even if someone does not provide any doc strings, the auto-generated documentation has useful hyperlink structure to determine the shape of the code. Better yet, you can open up the repo in an editor, and follow rust-analyzer's go-to-definition (again, powered by the type system) as it takes you on a guided tour.

Without such tools, we're essentially attempting to solve the same problem Python has been trying to solve using tools like Sphinx, with dubious levels of success.

So, it's hard to feel motivated to work on something which ultimately does not address some of the primary causes underlying what makes documenting Nix human-power intensive.

(idealism.0, skepticism.0) I get distracted quite easily, so I started working on writing a CLI (using Rust) over nixos-rebuild that is meant to be used with infinisil 's sanix. As I was writing it, I couldn't help but be aware of how well developed the ecosystem for CLI tooling is in other languages, especially for automatic generation of documentation (again, because I do not have to write documentation twice: the bulk of the documentation task is done by defining the program itself). Yet, there is a lot of shell/perl code in the nix/nixos repo...

And that's not easy to document automatically.

Furthermore, part of the reason why I'm inclined to write such a CLI tool is in order to make it easy for others to pick up a flake-less approach. Nix contributors who have been around for a while are remarkably restrained in their discussion around flakes. I'm not so inclined to be so restrained (barring my anxiety and insecurity), since my learning experience with Nix/NixOS improved dramatically with the following simple rules:

1. Ignore 99.9% of blog posts, third party literature, and the NixOS wiki.
2. Ignore flakes. (Ignore flake-utils. Ignore flake-compat.)
3. Ignore home-manager.
4. Documentation may not be the problem. More documentation is likely not the solution. Something is happening but I can't quite put a finger on it.
5. Don't lose hope.

(empathy.0, community.0) In hindsight, I'm not sure I can articulate this point well enough, and in particular, I am not sure if I mostly wanted to use it as a soapbox to air unresolved "grievances", after coming across something in your earlier messages (nothing to do with you!). So, I'll leave it all unsaid.

What I can say with some degree of confidence is that I would not be continuing to learn about Nix, if it weren't for some small kindnesses shown to me by various documentation team members, who given my many idiosyncracies, could have found it easier to give me a repeat of my experiences elsewhere.

I would rather not have them burn out.