[whatwg/streams] Consider better styling for API intro notes (#907)

Compare the green notes at https://streams.spec.whatwg.org/#rs-prototype to those right below https://dom.spec.whatwg.org/#event-retargeting-steps.

We're different than them in that we only do one API per section, so at first glance that list style isn't that necessary. But the "domintro" style shown there is a bit better than ours in a few ways:

- Nice "For web developers (non-normative)" label, instead of "Note"
- Not everything is italic.
- They don't repeat the API name (E.g. instead of "The pipeThrough method provides..." we'd just say "Provides..."
- They give very bare-bones usage examples and notation, which is sometimes nice. For example, we could use `[, x]` to denote optionality, or spell out dictionaries even if the standard treats them as a single variable, or show that `tee()`s return value is usually used with destructuring, or insert `await` before promise-returning method calls... Could be nice.

Should we adapt? Should we do anything different than most specs do, because of our one-API-per-section nature? Thoughts appreciated. Once we have a plan, I'd like to turn this into a "good first bug".

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/streams/issues/907