Add a short name to the schema (required)

[foolip]

Fixes #490.

[foolip]

Self-review to point out some interesting bits.

[foolip]

Name of the spec is "CSS Anchor Positioning", but prefix not needed.

[foolip]

API because scheduling is a browser-internal thing as well. Similar argument to Navigation API.

[ddbeck]

browser-internal thing

Do we have any evidence that web developers know or care about this fact?

[foolip]

No, I don't think most web developers think about how work is scheduled unless they specialize in performance. But it's like "paint", "layout" or "fetch". Browsers do these things, but there are also APIs for them.

[ddbeck]

I think all of this is fine, so I'm approving it.

That said, I've made some suggestions, thinking about how we might want to use this field. I'm not strongly committed to these suggestions (or couldn't even settle one one, in some cases). So perhaps an approach here is to adopt the changes that you like and open issues for anything that we ought to document as a naming guideline/convention?

[ddbeck]

browser-internal thing

Do we have any evidence that web developers know or care about this fact?

[ddbeck]

To recap, I think these are some initial guidelines to emerge from the various edits here:

Short name guidelines

Above all else, observe these two principles:

• Prefer names that web developers would actually use. Ask yourself: could you imagine hearing this a meeting or written in an issue tracker?
• Be open to revising in response to developer use and feedback. Descriptive names are cheap to change, as compared to identifiers.

In the absence of more definitive names, start from these guidelines:

• Prefer sentence case, unless you must match an interface name, specification title, or conventional casing and punctuation.
• Prefer ordinary descriptive nouns ("Idle detection") over interface names ("IdleDetector"), specification titles ("Idle Detection API"), or metonymy ("IdleDetector.start()"). This is a judgment call; use your head (and a StackOverflow and GitHub issue search).
• If in doubt, choose the shortest plausible phrasing, but be open to revising it when someone is confused or complains. Someday we'll add a long name field, where we can be pedantic and consistent.
• Adhere to long-standing conventions, even when they're silly (e.g., "referer" or "pseudo-class").
• Specific issues:
  • 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").
  • HTML: Tags can stand in for the concept of an element (e.g., "<img>" not "<img> element" or "Image element").
  • JavaScript and Web APIs: If you must name a specific method, property, or other part of an interface, start with this template: <interface> <property/method/etc.> (e.g., "Array at()" not "Array at() method").
  • WebAPIs: Append "API" only if it's needed to avoid an ambiguity (e.g., "Navigation API" not "Navigation").

[foolip]

Thank @ddbeck, that encapsulates well the decisions we landed on so far. A few thoughts:

Prefer sentence case, unless you must match an interface name, specification title, or conventional casing and punctuation.

This is the hardest guideline to follow I think. Both specification title and conventional casing would lead us to View Transitions and Idle Detections, but I stuck with sentence case. The hard part is the inconsistency we'd have between these and a case like "Fetch priority", and how to draw the line.

I think we should list only the exceptions we've used, which so far is only matching API names, which are also written together, e.g., BroadcastChannel.

Adhere to long-standing conventions, even when they're silly (e.g., "referer" or "pseudo-class").

Neither of these cases are at play in the names we've used. Do you have a case in mind where we'll need to use this part of the guideline?

[foolip]

Need to check if position: sticky might be more common.

[foolip]

Oh right, this is the spec name, it's not code.

[tidoust]

Side note: all entries in browser-specs have a shortTitle property. That could be a useful place to look at when a specification title is needed.

Most of the time, the property value is derived from the spec's title automatically but it is sometimes set manually, and we'd be happy to improve the values as needed.

The short title is typically used by Bikeshed when a spec references a section in another spec. For instance, the AVIF's spec full title is "AOMedia Film Grain Synthesis 1 (AFGS1) specification". Its short title is "AVIF", and [[av1-avif#layer-selector-property]] would thus render as "AVIF § 2.3.2.2 Layer Selector Property" in a spec.

[foolip]

Thanks @tidoust, I didn't know about shortTitle. Looking over them, it looks like you're keeping "API" in more cases than we're leaning towards here. Do you have guidelines for which to use?

[foolip]

I'm going to merge this now and filing a new issue for the guidlines.

[tidoust]

Thanks @tidoust, I didn't know about shortTitle. Looking over them, it looks like you're keeping "API" in more cases than we're leaning towards here. Do you have guidelines for which to use?

I don't think (or don't recall ;)) that we gave much thoughts about keeping or dropping "API". The shortTitle property was mainly introduced for CSS specs. It seems fine to me to favor dropping API when possible. I created w3c/browser-specs#1177 to track this from a browser-specs perspective.

[captainbrosset]

• 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?