Introduce the "if then else" concept about nix.dev

[Qyriad]

Would you reconsider that? Right now there is no single resource that someone can read to understand how to use Nix. They have to read nix.dev, a ton of the Nixpkgs manual, a bunch of the Nix manual, and possibly extras like Nix Pills or the NixOS Manual, all scattered and in specific but unspecified orders, in order to be able to understand the rest of the required reading.

I entirely support individual sections of nix.dev not including everything, but if you don't even include basic stuff like core language syntax somewhere in this resource then the Nix documentation problem is just going to get worse.

[fricklerhandwerk]

Right now there is no single resource that someone can read to understand how to use Nix.

Yes, and we're working on fixing that. It just takes time, enormous amounts of time. I'm not happy with it, either.

But let's also be clear: If eventually the Nix manual arrives at a state where I can say it's probably good enough, reading that back to back should give you a good idea of how Nix works and how to use it. That won't and is not supposed to help you navigate Nixpkgs, and certainly not NixOS. Those are different tools altogether, and blurring the boundaries in the past is part of what got us into the mess we're in at the moment.

If by "understand how to use Nix" you mean "the Nix ecosystem", then nix.dev is supposed to be that place, but it will by necessity have to be superficial. Nixpkgs just has way too large of an API surface to handle right now. We'll have to converge to a reasonable user experience from multiple ends:

• clean up the implementation and architecture, automate more of how reference documentation is presented, and fill it with content
• write much better contributor documentation so it stops getting messier
• write guides and tutorials on how to use what's there

But all those things are still far away in my opinion, like years away. We don't have the kind of resources to get this done faster. It's not like we didn't try. In particular, writing guidance requires solid reference documentation and a solid understanding how to use a given API effectively. In the documentation team we often find that there is neither, and have to come up with both on the fly.

And I'm not even talking about NixOS. There, documentation is essentially not maintained, which certainly contributes to an impression of it being a complete train wreck. We'd gladly help obtain merge permissions if anyone wants to take the responsibility.

They have to read nix.dev, a ton of the Nixpkgs manual, a bunch of the Nix manual, and possibly extras like Nix Pills or the NixOS Manual, all scattered and in specific but unspecified orders, in order to be able to understand the rest of the required reading.

Yes, and that's terrible. The reason I see for this is that, over the course of literally two decades, people have put all kinds of unrelated information all over the place, and rarely into the reference documentation on the given subject. (Here's an example where a language overview was in the NixOS manual of all things.) The system is so large, no one can clean that up on a whim without breaking existing navigation paths for hundreds of people relying on them every day.

if you don't even include basic stuff like core language syntax somewhere in this resource then the Nix documentation problem is just going to get worse

But that's exactly what I wrote in #817 (comment): The full syntax belongs to the Nix manual. I already started putting bits and pieces in there, as I go over various sections. I'd do it more systematically, but the process of getting things merged is so messy and unpredictable that it doesn't make sense to pile up a lot of work. It'll just stall and produce more work later.

I'll gladly merge more syntax definitions if you have time to add them. 🙂 Just please make small PRs because there's always a chance that one small bit will require back and forth and block everything else.

Generally, we can use lots of help to shovel around and sort out all that scattered information. The contributor guide for documentation lists a few general things one can do to support the effort.

[fricklerhandwerk]

This should find a place in a Nix language deep dive tutorial #579

[infinisil]

Relaying @fricklerhandwerk's comment on Matrix:

this [the tutorial] is not supposed to be a complete overview but shall rather point out things that are both important and unusual about the language. Conditionals are neither, therefore they aren’t there. The article is very long already.

[Qyriad]

If the tutorial isn't meant to be a complete guide to the language, then what is? nix.dev is lacking that.

[fricklerhandwerk]

The primary resource is the language chapter of the Nix manual. And that still needs a lot of work. The entire rest of nix.dev is about using the language in practice.