(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.

In reply to @jade_:matrix.org
i guess there's two separate issues: stuff that's genuinely not documented and stuff that's only documented in the source or documented twice

Maybe? Not sure. I can't help but think I lost the thread while writing that message, and therefore, readers would have too. But if I were to try again, much more succinctly:

1. Automation is useful, and important, especially given the context we are in. Nix has peculiarities which make it difficult to document semi-automatically. Should these peculiarities be addressed directly first? Or should we "accept reality as it is", and merely paper over Nix?

2. For a beginner (speaking as a beginner), learning Nix is especially difficult not because the Nix docs don't have good SEO, or because there isn't enough documentation. It's because there is a ton of noise; some of it quite purposeful/intentional.

In reply to @jade_:matrix.org
yes, this is exactly my observation as well. people claim the docs are inadequate but there's actually a lot of them, they're just hard to find what you want i guess?

Hmm. Yeah. I wouldn't complain if someone made a search engine dedicated to searching through all official nix docs through a single location. But I would also have been happy with the following:

1. Show me how to make custom "search engine queries" in my browser (Chromium, Firefox, etc.), so that I can do something like "@nixopt gnome-keyring" and it jumps to search.nixos.org with a query for gnome-keyring. Similar things can be done for a lot of nix resources. (Also kind of teaches me how to fish, and semi-automate searching for a lot of other programming tools' docs.)

2. Show me how to effectively search through Github for nix-lang code, and tell me which repositories are particularly excellent to use as examples, apart from nixos/nixpkgs.

Admittedly, this is far from ideal, but it's good enough.

In reply to @jade_:matrix.org
yes, this is exactly my observation as well. people claim the docs are inadequate but there's actually a lot of them, they're just hard to find what you want i guess?

Hmm. Yeah. I wouldn't complain if someone made a search engine dedicated to searching through all official nix docs through a single location. But I would also have been happy with the following:

1. Show me how to make custom "search engine queries" in my browser (Chromium, Firefox, etc.), so that I can do something like "@nixopt gnome-keyring" and it jumps to search.nixos.org with a query for gnome-keyring. Similar things can be done for a lot of nix resources. (Also kind of teaches me how to fish, and semi-automate searching for a lot of other programming tools' docs.)
2. Show me how to effectively search through Github for nix-lang code, and tell me which repositories are particularly excellent to use as examples, apart from nixos/nixpkgs.

Admittedly, this is far from ideal, but it's good enough to make progress with.

In reply to @jade_:matrix.org
and the conceptual or how things fit together level is not that good

For me that is sort of a noise problem again? I would never have found this via googling. I don't think I have seen any third party blog post mention it.

Similarly, I would have benefited from reading something along the lines of: "forget about home-manager and flakes for now; once you understand Nix/NixOS better, you'll be better placed to use them, and judge whether they are useful for you..."

But for reasons that are...somewhat political?...there is a lot of smoke around this.

In reply to @jade_:matrix.org
so errr. yeah there are political reasons but oddly enough, the official docs are essentially completely not flakes. and i agree that every random blog post telling you to use home manager is pretty sad.

In reply to @jade_:matrix.org
so errr. yeah there are political reasons but oddly enough, the official docs are essentially completely not flakes. and i agree that every random blog post telling you to use home manager is pretty sad.

In reply to @tejing:matrix.org
It's really hard to communicate the status of flakes to a newbie

In reply to @tejing:matrix.org
every newbie and his brother is convinced everything under the sun "requires flakes"... I suspect because they're doing a lot of their learning from people who don't actually understand things themselves all that well, and only learned flakes