Revise performance timing entries' names and descriptions

[ddbeck]

A follow up to #4237.

[tunetheweb]

Mostly LGTM but if we're capitalising some, then I'd capitalise them all. The specs mostly treat these as proper nouns (though not in all places I've noticed!).

And similarly I'd suggest adding "peformance entries" consistently.

I've also suggested changes to Visibility State and Resource Timing to make them clearer.

[tunetheweb]

Suggested change

	name: Element timing
	name: Element Timing performance entries

[tunetheweb]

Suggested change

	name: Layout instability
	name: Layout Instability performance entries

[tunetheweb]

Suggested change

	name: Navigation timing
	name: Navigation Timing performance entries

[tunetheweb]

Suggested change

	name: Paint timing
	name: Paint Timing performance entries

[tunetheweb]

Suggested change

	name: Resource timing
	name: Resource Timing performance entries

[tunetheweb]

Suggested change

	name: Soft navigation performance entries
	name: Soft Navigation performance entries

[tunetheweb]

Suggested change

	description: A `PerformanceResourceTiming` performance entry records when a network event happens while loading a resource, such as when a connection starts and ends. You can use this information to measure loading times.
	description: A `resource` performance entry records network event timings, such as when a connection starts and ends or loading time, for resources requested by a page.

[tunetheweb]

Suggested change

	name: Page visibility state
	name: Page Visibility State Entry performance entry

I think this is especially important to rename to differentiate it from page-visibility.yml (which is related but different - one just gets the current state, the other monitors for changes).

[ddbeck]

Thanks for the early review, @tunetheweb!

I'm still not sure about capitalization. I agree we should capitalize proper nouns, but I'm not inclined to defer to specs as a rule. They're almost German in their tendency towards capitalization and, as you've noted, not consistently edited. "Paint timing" is a good example where even the spec is seemingly unconvinced that it's a proper noun, shedding the capitalization after the early sections.

Instead, I'd suggest we follow capitalization where the named measures have a well-known-to-developers initialism or it's likely to be known that way. Or, more generally, if there's a term of art that is likely to be capitalized by developers, but I don't think we have a good example in this batch.

In this case, I think that means we capitalize:

• Interaction Contentful Paint (ICP)
• Largest Contentful Paint (LCP)

And though they're not mentioned in feature names, in the description for the paint-timing feature we should continue to write:

• First Paint (FP)
• First Contentful Paint (FCP)

Are there any others you want to make a case for?

(Otherwise, consistency across these features would be good. I should also pluralize consistently here, with "performance entries.")

[tunetheweb]

Yeah it's a tricky one!

Some more thoughts:

I think to explain the spec choices (somewhat) there is a difference between using an API (e.g. "The page uses the Paint Timing API") and the concept ("this is used to measure paint timings - i.e. the timing of paints"). But the concept could also be worded in terms of the API ("this is used to measure the Paint Timing (as defined by the spec) of the page"). But that nuance is tricky to comprehend.

However for web features the concept is more important than the API IMHO so we probably shouldn't capitalise unless there's a well-known acronym/initialism as you say. That also fits with other examples of features like "View transitions" which is not capitalised, despite there being a "View Transition API" and a "View Transitions" spec. So plus one to that. And agree FP and FCP deserve that capitalism while others (e.g. "Navigation timing") do not.

When it comes to acronyms, there is another subtlety in that we have APIs (LargestContentfulPaint) and metrics ("Largest Contentful Paint (LCP)") and I agree the latter is what people know it as. The difference between the API and the metric is often razor thin (for FP and FCP they are pretty much the same as the API emits the metric, for LCP it's different as the LCP metric is calculated from a number of LargestContentfulPaint entries). Anyway, TLDR: when there is a well-known metric initialism that the API is primarily used for, I agree that should be the name and capitalism therefore makes sense.

But this introduces another couple of oddities:

• Interaction to Next Paint (INP) is the metric measured by the Event Timing API. But the feature is currently called "Event timing" and not "Interaction to Next Paint (INP)". Though that is included in the description. I think this is fine as is, and it's been out for a while, but is a slight deviation from what I said above.
• "Interaction Contentful Paint" is not a metric, and so not that well-known by it's initialism. In fact I've been careful to avoid calling it ICP in case people presume it's a metric. Plus it's easy to mistake for LCP when you see it written depending on the font and how easy it is to distinguish I from L. So I'd say this probably should stay "Interaction contentful paint" feature, rather than "Interaction Contentful Paint", but that might be jarring since it's inconsistent with "Largest Contentful Paint" and "First Contentful Paint" (which are both APIs AND metrics). Maybe we should just avoid capitilization even when there is a well-known initialism?

So, at the end of that meandering thought, I think I'm back to NOT capitalising them after all! Even if there's a well-known initialism.