The docs about exit values could be a lot better #1251
Description
What is the type of issue?
Something else
What is the issue?
The docs about exit values: https://effect.website/docs/data-types/exit/
Most users are going to experience exit values as something that the system emits, like from runPromiseExit or runSyncExit, not by constructing themselves. This is the entrypoint to Exits. But the docs start out by saying how you'd construct your own exit objects. However, the docs do not demonstrate why you would want to construct your own exit objects. I don't know why I'd ever want to construct an exit object by hand - can you yield it in an effect chain? Would you use it as a fixed no-op return value maybe? A real world example is not obvious for this one.
Improvement: this should probably walk the user through the most common place where they'll encounter exits (by running a program), and focus on pattern-matching first, because that is a common need and creating exits second, because that is niche.
The Exit vs Effect docs are super rough. They say that "Exit is actually a subtype of Effect," and how succeed and fail are "essentially the same" as Effect's versions. And then that 'An Exit, in essence, is a “constant computation”.' - what does this mean? It's too poetic and not very helpful.
Improvement: this could say why an Exit is different than an Effect and why that is useful. I can gather that Exit is the result of running a program, and that unlike an Effect, its state can always be known synchronously, and that it doesn't have Requirements. Those things are useful for the result of a program and otherwise would be annoying if it was really runPromiseEffect and you'd get an effect that you still had to yield. And Exits wrap their errors in Cause, I think?