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