Guidelines for short names

[foolip]

Short names were added in https://github.com/web-platform-dx/web-features/pull/545 and @ddbeck suggested guidelines at https://github.com/web-platform-dx/web-features/pull/545#issuecomment-1913286828.

[foolip]

It's worth thinking more about sentence case vs. Capitalizing Every Word. https://github.com/web-platform-dx/web-features/pull/545 was merged with sentence case. I've sent https://github.com/web-platform-dx/web-features/pull/549 to show what would change if we capitalize.

These cases are not great with sentence case:

• Cascade layers and Container queries, which I've seen capitalized many, many times.
• Constraint validation API, where the trailing "API" makes it look more like a typo.
• Web animations, which seems more generic and might cover CSS animations as well.

And these cases are not great when capitalized:

• "Flexbox Gap", but we could make it "Flexbox gap"
• "input Event", although that would be less strange as "input Event"
• More generally, any name that ends with "attribute", "event", "method", "property" or similar, which we'll have more of in a future long name. Consider "CSS aspect-ratio Property", where aspect-ratio feels squashed in between those Big Words.

@tidoust also pointed out that https://github.com/w3c/browser-specs has a shortTitle property, and that capitalizes every word.

I'm still leaning towards keeping sentence case, but am not at all committed to it.

[tidoust]

Regarding shortTitle property values in browser-specs, the W3C Manual of Style recommends to "Capitalize title words following U.S. usage". Most if not all specification titles follow that convention.

The same manual also lists some commonly misspelled terms with the example of "real-time communications", where capitalization depends on whether the term is used in titles and headings (and references to titles and headings) or to talk about the generic idea.

Applied to web-features, the rule of thumb could perhaps depend on whether the feature has a strong bond with a specification or a heading in a specification (e.g., "Container Queries" could perhaps be seen as strongly tied to the "Container Queries" section of the CSS Containment spec), or whether we're more talking about a generic idea, or a generic idea applied to something specific (e.g., "CSS aspect-ratio property" because property is a generic idea. Plus the spec actually uses lowercase in the heading for that ;))

[captainbrosset]

I made some comments about the guidelines listed in #545 which, I'm realizing now, would make more sense in this issue here:

• CSS: Let syntax and casing—such as : (for pseudos), @ (for at-rules), and kebab-case—do the talking (e.g., ":indeterminate" not ~":indeterminate pseudo-class"~).

I'm on the fence about this one because I always think about beginners. It feels much more beginner-friendly, from my opinion, to say things like "has pseudo-element" rather than ":has", or "dialog html element" rather than "<dialog>".

Note that it could be a mix of both: ":has pseudo" and "<dialog> element". But, asking people to recognize a tiny syntax character to know what we're talking about feels like an unnecessary barrier to me.

• HTML: Tags can stand in for the concept of an element (e.g., "<img>" not ~"<img> element"~ or ~"Image element"~).

What if we have an SVG element feature at some point. How would someone know if "<foo>" is SVG or HTML?

[foolip]

@captainbrosset do you think a longName or structuredName would address the first concern? I'm imagining names like "CSS aspect-ratio property", "CSS :has() functional pseudo-class", or "HTML <dialog> element" for those.

For the <tagname> convention, I'd say that <tagname> means HTML, and we should prefix with SVG to disambiguate, like here: https://github.com/web-platform-dx/web-features/blob/3ea8af9e4aef6097759556ca988cc35703cade90/feature-group-definitions/svg2-script-html-equivalence.yml#L1

[foolip]

https://github.com/web-platform-dx/web-features/pull/565 is a case where I felt like "CSS translate, scale, and rotate properties" was the short possible name. Guidelines should at least allow for that, or ideally guide us in the same direction in the same situations going forward.

[captainbrosset]

Sure, a long name would address my concern. But now I'm wondering if we need ID, shortName, and longName. Maybe just ID and longName?

[foolip]

We might be able to get away with a single kind of name, I'm not sure. Right now there are no consumers for the names we've added, and probably a good next step is to talk to some people we think will show them...

caniuse.com is the main consumer I have in mind, so looping in @Fyrd here.

[ddbeck]

Mentioning https://github.com/web-platform-dx/web-features/pull/291 so we can have a guideline for HTML attribute features, someday.

And editing to add: https://github.com/web-platform-dx/web-features/pull/321

[foolip]

Copying what I wrote in https://github.com/web-platform-dx/web-features/pull/624#discussion_r1491913076:

We have no guidelines for when the name should look like code or not, but some precedent. So far we have these names with () in them:

• :has()
• :indeterminate()
• :is()
• :where()
• Array at()
• Array flat() and flatMap()
• checkVisibility()
• color-mix()
• CSS abs() and sign()
• CSS calc()
• CSS calc() constants e, pi, infinity, and NaN
• CSS min(), max(), and clamp()
• CSS pow(), sqrt(), hypot(), log(), exp()
• CSS round(), mod(), and rem()
• CSS sin(), cos(), tan(), asin(), acos(), atan(), and atan2()
• image-set()
• input.showPicker()
• scrollIntoView()
• select.showPicker()
• structuredClone()

Roughly, my thinking has been that when adding () or other small pieces of syntax hints towards what kind of thing it is, then do it even though it's not minimal. My thought has been that we'll eventually mark up names with <code> and have names like this:

• :has()
• Array flat() and flatMap()
• CSS abs() and sign()
• input.showPicker()
• structuredClone()

I think this has very little downside in the cases of global/static things like :has() or structuredClone().

For instance methods (stuff on prototypes) it's a little bit inconsistent, already. I think we should favor short names, and for Array the style works.

For HTML elements it's a bit awkward and I'm not sure the choices so far will stand, but the alternatives to input.showPicker() that I've considered are worse IMHO:

• HTMLInputElement.prototype.showPicker() (much worse)
• HTMLInputElement showPicker()
• <input> showPicker()

[foolip]

@ddbeck had some very useful thoughts and feedback in https://github.com/web-platform-dx/web-features/pull/655#issuecomment-1980936576. Noting that here since I'll merge the PR, to not lose the discussion.

[foolip]

What to do about the Web prefix has come up in https://github.com/web-platform-dx/web-features/pull/691, so I'll write down my thoughts here. Our guideline is "Avoid frequently-used abbreviations and nouns, such as API and Web", but I had to use the example "web workers" as one of the few "obvious" cases, and I don't think we can always omit Web.

Based on MDN and what's in WPT, here's a fairly comprehensive list of what the specs call themselves:

• Web Animations
• Web Audio API
• Web Authentication
• Web Bluetooth
• Web Cryptography API
• Web Locks API
• Web MIDI API
• Web Neural Network API
• Web NFC
• Web Serial API
• Web Share API
• Web Share Target API
• Web Speech API
• WebCodecs
• WebGL (multiple specs)
• WebGPU
• WebHID API
• WebOTP API
• Web Packaging
• WebRTC (multiple specs)
• WebSockets
• WebTransport
• WebUSB API
• WebVTT
• WebXR Device API (multiple specs)

A few more phrases that aren't the names of specs:

• Web Components: refers to Shadow DOM, Custom Elements, etc.
• Web Messaging: refers to postMessage() etc.
• Web Notifications: refers to Notifications API
• Web Storage: refers to localStorage and sessionStorage
• Web Workers: refers (arguably) to the kinds of workers defined by HTML, but not service workers

[captainbrosset]

Also Web Bluetooth.

[captainbrosset]

There's a visual difference in these names, which I'm not sure carries meaning. Web Share (with a space) and WebGPU (no space).

@tidoust does that mean anything in W3C spec land?

[tidoust]

@tidoust does that mean anything in W3C spec land?

No. The title gets reviewed when a spec enters the Recommendation track, and sometimes changed to better align with the naming used in other specs, but that's done on an ad-hoc basis, and without a clear set of rules.

The Manual of Style has a minimal set of guidelines on the title, essentially "Capitalize title words following U.S. usage". To my knowledge, there has not been any attempt at harmonizing titles across specs (e.g., to add/remove "API", to use a "Web" prefix, or to use a space after "Web").

I also note the Naming principles in the TAG's Web Platform Design Principles document.

[foolip]

Here are my opinions on all of this. Where I don't think we should include Web in the name / identifier:

• Things from the HTML5 era: Web Messaging, Web Storage and Web Workers all have better names
• Web Notifications is just notifications

I'm not too sure about these:

• WebOTP API is related to Credential Management and might be called a subfeature of some sort
• WebCodecs is one feature, but could be split up similar to Web Speech

In all other cases I think Web should be included, for a few different reasons.

Because what comes after is a very generic word:

• Web Animations, this could be called the Animations API alongside CSS animations and SVG animations, but nobody does?
• Web Audio API
• Web Authentication
• Web Cryptography API
• Web Locks API
• Web Packaging
• Web Serial API
• Web Share API
• Web Share Target API
• Web Speech API (actually two features now, recognition and synthesis)

Because what comes after is a technology that also exists outside the web, and is sometimes a trademark:

• Web Bluetooth
• Web MIDI API
• Web Neural Network API is sometimes called WebNN, which would put it in this category. The API entrypoint is navigator.ml, so it could be called "machine learning" too.
• Web NFC
• WebGL
• WebGPU
• WebHID API
• WebUSB API

Because Web is part of the name in syntax or API:

• WebSockets
• WebTransport
• WebVTT

Because the name is well established:

• WebRTC
• WebXR Device API and other WebXR features

[atopal]

Your reasoning makes a lot of sense to me, but why the exception for something like notifications? It seems to me like that would be inline with "Because what comes after is a very generic word", which I think is a good reason to add the prefix.

[foolip]

Mostly because the name of the spec is Notifications API. It must have been called Web Notifications by someone at some point, but that's not how I know the feature at least. Push is similar, sometimes called Web Push. I'd put these in the same category as the HTML5 era things, where the Web prefix didn't stick.

[ddbeck]

The "should we omit API from names?" question came up on the WebDX call today. I'd like to partly unroll this. We have two broad (and overlapping) groups of features to contend with:

1. Older features where can directly observe or ask web developers how they talk about those features (e.g., Stack Overflow, etc.).

2. Newer features where there's less to go on from the audience of web developers.

In the former case, we collect some evidence and make a call. That feels easy-ish. If the term "API" is genuinely inseparable as used by developers, then we accept it. I suspect there aren't that many cases where web developers won't know what we're talking about if we don't use the term API, but that does mean that sometimes we'll have to use it.

In the latter case—if this project is generally successful—we have the possibility of choosing the name that web developers will see. That feels a little higher stakes. I suppose aesthetically I'd rather not canonize "API" in those cases. But also I worry that a real risk is getting an idiosyncratic name: one that came from a spec author or first person to blog about a feature, rather than several people thinking about or working with the feature. With that in mind, I think it's kinda nice to put the name to a discussion here in PR reviews—it's at least a nod toward the evolution that will play out amongst the broad group web developers over time.