Consider better styling for API intro notes

[domenic]

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

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".

[ricea]

I think "Not everything is italic" is the biggest selling point for me 😄. We'd need at least two types, because some of our notes are for implementers.

The DOM spec example looks more like our "Class definitions" than our "Note" sections. Moving usage notes into the "Class definition" and rewriting it in that style might be a way forward.

[domenic]

My latest take on this is in https://domenic.github.io/async-local-storage/; see e.g. https://domenic.github.io/async-local-storage/#storagearea-set.

I'm undecided on whether we should have these domintro blocks in the method definitions (as the current notes or), or if we should consolidate them all into one place per class. A nice feature of the latter is that it allows us to replace the class definitions, which have caused significant confusion (#45, #732, and some recent IRC conversations).

[surma]

I like the way it looks in your async-local-storage draft.

You still have a class definition in the current draft. I think they should not get nuked as they make the spec very navigational (provided that they get linked up in the same way I’ve done in #872 and #913).

(edit: Just realized that the “see below” is a link. Could be enough, but it seems more intuitive to me to make the method name itself a link.)

[domenic]

That's a bit different, as there it's used to normatively create the class.

I think if all the domintros were consolidated into one block (see e.g. below the IDL block at https://dom.spec.whatwg.org/#interface-abortcontroller) then having the class definition nearby would be just redundant. So that's why we'd get to nuke the class definition.

If we keep them spread out, as I've done in async-local-storage, then yeah, the class definition or some similar table of contents (perhaps just the normal table of contents?) would be needed.

[surma]

I acknowledge that all the info a developer would need is in there. I feel a bit hesitant about diverging from other specs which also have IDL or at least some sort of code-y representation. It feels like it doesn’t skim-read very well, but maybe it’s just because I am not used to that layout.

So I am cool with your approach, but I still do like the clickable class definitions.