clarify advice on synchronous versus asynchronous APIs

[dbaron]

The discussion in w3ctag/design-reviews#439 (and really the discussion at TPAC in Fukuoka that led to filing it) point to the issue that the advice in the design-principles document on synchronous versus asynchronous APIs is perhaps too strong, or at least can be interpreted in too strong a way. It points out the reasons to prefer asynchronous APIs, but doesn't address possible tradeoffs against them.

(Two examples from that particular issue are (a) tradeoffs against user convenience and (b) tradeoffs against racy behavior that results from an API answering a question whose result might vary depending on whether the document is currently handling a user gesture.)

There's more detail after following the link above (and further links from that).

It should probably clearer how strong the advice to prefer asynchronous APIs is (which may differ across the various reasons) and what factors should be considered in the other direction.

[alice]

Earlier: #81

[hober]

@cynthia to draft a PR.

[torgo]

We discussed today and came up with the idea of a subsection providing guidance on "when to use synchronous".

[cynthia]

I've removed the "should not fail" and replaced it to "not expected to be gated behind a permission".

[cynthia]

Discussed in today's call; we've noticed that the principles document tends to advocate async, and we should probably tweak the tone throughout the document so it doesn't feel like we are advocating async.

[alice]

Adding a note here to update the "Design asynchronous APIs using Promises" section of design principles as part of this work.

[torgo]

Discussed on 05-01 and agreed to close as this is done.