I think this would be useful to have an example of. What do you think about one or the other of these two "adding with an artificial delay" examples using a randomized delay?

(Also, some more explicit information about what happens to the slow update would be nice. I'm imagining it's just getting discarded?)

what about just linking to something like this?

@Rich-Harris I don't think that quite answers the question I immediately get from this, which is "If update 1 finishes after update 2, does it clobber the result of update 2 or get discarded"?

Oh, maybe, for part of it. Synchronous updates (or as close as we currently have to synchronous updates) doesn't feel quite the same in terms of being a 'fast' update as a fast async update would, I don't think.

I don't know how fancy we want to get here in these examples. There are a couple of things going on here. One is synchronous updates continuing to happen while waiting for async updates. One is two different independent async updates happening independently. And one is multiple async updates of the same data happening, possibly completing out of order. If you want to gloss over at least some of these in this initial pass at the documentation, that's probably a reasonable idea.

Yeah, I do like the idea of not getting too bogged down in details because a) they might change before the experimental flag comes off, b) we don't yet really know which bits people will find confusing and c) most people don't care about this level of detail anyway

(and if people want the answer to questions like 'does it clobber the result of update 2 ...' they can just try it and see)

will merge in the meantime, we can iterate as needed