Guideline for API names and descriptions

[foolip]

In #810 and #752 we have some names and descriptions that feel a bit quirky compared to how most resources talk about them.

Should the name be:

• Audio session or Audio Session API
• Media session or Media Session API
• Device posture or Device Posture API

Should the description start with:

• The navigator.audioSession object, the navigator.audioSession API, or the Audio Session API?
• The navigator.mediaSession object, the navigator.mediaSession API, or the Media Session API?
• The navigator.devicePosture object, the navigator.devicePosture API, or the Device Posture API?

Considerations:

• If we include "API", do we always do it or only when that's the spec name? https://w3c.github.io/device-posture/ includes it but the other two do not
• Calling something "object" is technically correct, but I worry that it overfocuses on the API entry point, and that the features aren't normally referred to be their entry point, especially things on navigator, since navigator is effectively a namespace to avoid putting stuff on window.

[foolip]

#762 is another feature we might want to revisit.

[foolip]

And #771, which I just merged with the description "The PressureObserver API ..."

[ddbeck]

OK, I've been thinking over this general problem of "never say API".

For feature names, I think we made the right choice: we do not want to create features that have the appearance of having "completed" an API. Suppose the Media Session API acquires new and interesting capabilities. A "media session" feature is still usable, even if the whole of the Media Session API is not implemented. Naming "Media Session API" makes it harder to draw that distinction.

That said, I'm thinking that "Device Posture API" or "Media Session API" would be very good groups (and will inevitably appear in snapshots).

That leaves descriptions: I'm more comfortable with descriptions being a moving target. So initially any feature could start with "The Special API does …" or similar. When follow-on features appear, those descriptions can change to reflect that without losing the stability of the feature name.

[foolip]

API in group names sounds reasonable, and groups would tend to more often match whole specs and their names. I've sent #861 for Web Speech API.

This does put additional pressure on capitalization though. "Web speech API" looks very opinionated about capitalization when we're taking extra steps to disagree with the spec name. Looking back at #549, I think most names aren't made worse with title capitalization. The borderline cases are where we've had to mint a name, and when capitalizing it makes it feel more "official" than it is, like "Background Gradients". But I think it will raise fewer eyebrows than our sentence capitalization.

We should still use sentence caps in descriptions I think, so there might be some new tricky cases there.

Allowing backticks in names would also help a bit to distinguish names that are entirely lowercase because they're syntax.

[ddbeck]

FWIW, I suggested lowercase names when there were no groups or snapshots. A big part of my motivation was maintenance: it's easier to be consistent with one, consistent rule. We longer have that anyway, so I'm less inclined to fight for it.

cc: @Elchi3 maybe you have a take on this.

[ddbeck]

Allowing backticks in names would also help a bit to distinguish names that are entirely lowercase because they're syntax.

It'd be good to talk to consumers about what they'd like to see from us on string formats, whether they'd prefer unformatted plaintext, Markdown, or HTML.

[foolip]

I think we should generate plaintext and HTML from Markdown, and publish only those, not the source Markdown. So both name and nameHTML, description and descriptionHTML.

[foolip]

Alternatively we make it part of an API, so that we can also support linking between features and generating the right descriptions given a URL template or something.