What issue with the existing figure are you trying to address with the new figure? I honestly struggled to parse it a few times as I kept not really seeing the zorder =3 example, so I much prefer the current figure where the over and under cases are separated. I think the alpha is also maybe a drop too high and that's further not helping my ability to easily read it.

IMHO the current figure has some issues

• It's quite cluttered:
  • A table with an "Alpha value" column, but that value is already prominently stated in the titles.
  • Each Axes has a Legend and they look quite the same on first sight. - Better to directly write the zorder on the Artist rather than have the indirection via the legend.
• alpha = 1 is trivial: You draw the one with higher zorder on top. You certainly don't need two examples for that; I'd argue you don't need that at all.
• alpha = 0.3 is a value so low that I don't see a visual difference between the zorder at all. - What do we want to illustrate here?

Overall, this a lot of noise but I don't see a clear message we want to communicate with the figure. I suspect it should have something to do with the subsequent note "Re-ordering Artists is not commutative in Matplotlib." / "Changing the order of Artists will generally change the resulting figure." The first version was not comprehensible and was changed to the second version. While correct, the statement is essentially trivial: If you change the order and thus change what is drawn on top, the result may change. The only maybe not completely trivial case is if transparency is involved. That's what I've tried to illustrate in the figure: If you draw the blue alternatively above or below the red square, the mixed region is still not the same. - Though I have to admit, that if one thinks about it for a second and considers only a slight transparency this is also clear: The result is still mostly dominated by the color in front.

Reconsidering, I think the whole front/back discussion here is overemphasized and mostly beyond the scope of what we need to communicate in the context of transparency. Maybe after the equation we should just give an illustration

The following plot shows an orange rectangle in the background and a set of blue rectangles with varying transparency in the front:

I really like your illustration cause that covers the problem of zorder not really mattering for a bunch of alpha levels and then yeah we can link out to zorder.
Also that picture looks so compact that I wonder how much space a second figure under your first with the orange on top would take up.

Commited with the new proposal.

I wonder how much space a second figure under your first with the orange on top would take up.

What do you want to communicate with that? We'd need to add an alpha to the orange bar, otherwise it's quite meaningless:

With alpha=0.8

but we have to say a lot more, namely the bar alpha and the changed zorder, which makes it more buy.

One could also put both in one figure, but still this needs all the context information.

Overall, I think the simple illustration is enough.

I like the last one. Like it or not, people are confused by this.

I don't know that we need 10 alpha values if we want to make the figure narrower.

I like the last one. Like it or not, people are confused by this.

Agree, and I think the zorder and orange bar labels can basically go in the fig caption/side bar since they're useful annotations but not the main point. Something like:

ETA: If you're worried about busy, there's a new viz paper that says that folks like heavy annotations in visualizations https://arxiv.org/abs/2209.10789

Ok, added the two-row exmaple.

On my phone and it won't let me c&p properly but the doc build failure is b/c of the tutorial & I wish there was a way to dump this at the end of the build.

Eta: far as I'm concerned it can be merged by anyone (including a self merge) after doc build is fixed.