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

In reply to @tejing:matrix.org
I'll also mention this tidbit here in case others find it a little useful: We talk about the relationship between how nix manages files and how programming languages deal with pointers, but for some reason when it comes to explaining why we avoid well-known paths, nobody seems to make the comparison to avoiding global variables

Could it be, to some extent, because Nix's current tooling relies fairly heavily on things like environment variables?

I'm reminded of nix-shell/nix develop

In reply to @bzzm3r:matrix.org

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 @olafklingt:matrix.org
I think most of the noise is not intentional. The difficult part of improving the documentation is not to add content but to make it more concise. So i basically agree with your observations.

In reply to @olafklingt:matrix.org
I think most of the noise is not intentional. The difficult part of improving the documentation is not to add content but to make it more concise. So i basically agree with your observations.