Reduce Performance APIs to a single group #22031

Elchi3 · 2022-11-03T11:28:20Z

Description

The Performance API consists of a few specs, however, web developers don't really need to know about this. Important is that the web platform offers a Performance API to measure web application's performance and we should present all the measurement possibilities at a central place where you can learn about all of them and which one is suitable in which situation.

Motivation

openwebdocs/project#62

Additional details

I updated the list of guides in groupData as well, but note that they will all be rewritten and we will have one guide to all Performance APIs.

There is a weird mix of APIRef and DefaultAPISidebar. Maybe we can fix that some other day, though.

Related issues and pull requests

#21984 updates the main Performance API overview page and will be the new main page for all Performance APIs.

github-actions · 2022-11-03T11:53:27Z

Preview URLs (151 pages)

Flaws (24)

Note! 141 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/API/Navigation_timing_API
Title: Navigation Timing API
Flaw count: 1

macros:
- /en-US/docs/Web/API/Window/performance redirects to /en-US/docs/Web/API/performance_property

URL: /en-US/docs/Web/API/Navigation_timing_API/Using_Navigation_Timing
Title: Using Navigation Timing
Flaw count: 2

macros:
- /en-US/docs/Web/API/Window/performance redirects to /en-US/docs/Web/API/performance_property
- /en-US/docs/Web/API/Window/performance redirects to /en-US/docs/Web/API/performance_property

URL: /en-US/docs/Web/API/PerformanceTiming
Title: PerformanceTiming
Flaw count: 1

macros:
- /en-US/docs/Web/API/PerformanceTiming/toJSON does not exist

URL: /en-US/docs/Web/API/PerformanceNavigationTiming
Title: PerformanceNavigationTiming
Flaw count: 2

macros:
- /en-US/docs/Web/API/PerformanceNavigationTiming/requestStart does not exist
- /en-US/docs/Web/API/PerformanceNavigationTiming/responseStart does not exist

URL: /en-US/docs/Web/API/DOMHighResTimeStamp
Title: DOMHighResTimeStamp
Flaw count: 1

bad_bcd_queries:
- No BCD data for query: api.DOMHighResTimestamp

URL: /en-US/docs/Web/API/Performance
Title: Performance
Flaw count: 1

macros:
- /en-US/docs/Web/API/Window/performance redirects to /en-US/docs/Web/API/performance_property

URL: /en-US/docs/Web/API/PerformanceNavigation
Title: PerformanceNavigation
Flaw count: 2

macros:
- /en-US/docs/Web/API/PerformanceNavigation/toJSON does not exist
bad_bcd_links:
- no explanation!

URL: /en-US/docs/Web/API/PerformanceEventTiming
Title: PerformanceEventTiming
Flaw count: 11

macros:
- /en-US/docs/Web/API/HTMLElement/pointerover_event redirects to /en-US/docs/Web/API/Element/pointerover_event
- /en-US/docs/Web/API/HTMLElement/pointerenter_event redirects to /en-US/docs/Web/API/Element/pointerenter_event
- /en-US/docs/Web/API/HTMLElement/pointerdown_event redirects to /en-US/docs/Web/API/Element/pointerdown_event
- /en-US/docs/Web/API/HTMLElement/pointerup_event redirects to /en-US/docs/Web/API/Element/pointerup_event
- /en-US/docs/Web/API/HTMLElement/pointercancel_event redirects to /en-US/docs/Web/API/Element/pointercancel_event
- and 5 more flaws omitted
broken_links:
- Can't resolve /en-US/docs/Web/API/Event/timestamp

URL: /en-US/docs/Web/API/PerformanceEntry/startTime
Title: PerformanceEntry.startTime
Flaw count: 2

broken_links:
- Can't resolve /en-US/docs/Web/API/Event/timestamp
- Can't resolve /en-US/docs/Web/API/Event/timestamp

URL: /en-US/docs/Web/API/PerformanceServerTiming/toJSON
Title: PerformanceServerTiming.toJSON()
Flaw count: 1

macros:
- wrong xref macro used (consider changing which macro you use)

(this comment was updated 2022-11-04 16:57:36.352526)

wbamberg

So fiddly, this.

wbamberg · 2022-11-03T23:08:26Z

files/jsondata/GroupData.json

+        "/docs/Web/API/User_timing_API/Using_the_User_Timing_API",
+        "/docs/Web/API/Element_timing_API",
+        "/docs/Web/API/Paint_timing_API",
+        "/docs/Web/API/Largest_Contentful_Paint_API"
      ],
      "interfaces": [


I believe that three lists of interfaces need to match:

the list of interfaces here

the list in the perf overview page

the set of interfaces (and subpages) that are calling APIRef("Performance API")

We have to maintain all three lists manually because our infra is so bad (see also openwebdocs/project#76 (comment)).

I've been through the Perf WG specs and made a list of all the interfaces that seem relevant:

EventCounts InteractionCounts LargestContentfulPaint Performance PerformanceEntry PerformanceEventTiming PerformanceLongTaskTiming PerformanceMark PerformanceMeasure PerformanceNavigation (obsolete) PerformanceNavigationTiming PerformanceObserver PerformanceObserverEntryList PerformancePaintTiming PerformanceResourceTiming PerformanceServerTiming PerformanceTiming (obsolete) TaskAttributionTiming

The groupdata entry here does seem to be consistent with the perf overview page, but there a few discrepancies between both of them and my list:

you are missing InteractionCounts. I suspect actually both this and EventCounts should not get their own pages but should be documented inline. But I think what we do for one we should do for both.

you have PerformanceElementTiming, but this is a WICG interface. Still, it is already documented. Not sure what to do here or what our general policy is on WICG specs. I suspect we have a lot of them already.

you are missing PerformanceNavigation and PerformanceTiming

Compared with pages that have APIRef("Performance API") in this PR:

you have it for the PerformanceNavigation and PerformanceTiming pages

you have it for DOMHighResTimestamp, which isn't an interface of course. IMO we should delete this page, per Delete DOMTimestamp and EpochTimestamp #17096, and just have a bit somewhere describing timestamps in the perf API.

you have it for PerformanceElementTiming

you are again missing InteractionCounts

So I think we need to:

add PerformanceNavigation and PerformanceTiming to groupdata and the perf overview page

get on with deleting DOMHighResTimestamp

either add InteractionCounts, or remove EventCounts, probably the latter

you are missing InteractionCounts. I suspect actually both this and EventCounts should not get their own pages but should be documented inline. But I think what we do for one we should do for both.

So, both are interfaces, and I thought our policy is that we always document interfaces on their own page. BCD will always have data for interfaces, too. The reason that EventCounts is there and InteractionCounts isn't, is that InteractionCounts isn't supported anywhere yet but EventCounts is. (and so there is BCD for EventCounts and not for InteractionCounts).

you have PerformanceElementTiming, but this is a WICG interface. Still, it is already documented. Not sure what to do here or what our general policy is on WICG specs. I suspect we have a lot of them already.

It was already documented and has an implementation, so I think we should care about it.

you are missing PerformanceNavigation and PerformanceTiming

Both are deprecated. I'm happy to add them, but maybe it would be better to discourage them as much as possible?

get on with deleting DOMHighResTimestamp

Yes, I think we should do this. Need to make sure that performance docs can still refer to this type somewhere, though, I think. Will look into the PR.

you are missing InteractionCounts. I suspect actually both this and EventCounts should not get their own pages but should be documented inline. But I think what we do for one we should do for both.

So, both are interfaces, and I thought our policy is that we always document interfaces on their own page. BCD will always have data for interfaces, too. The reason that EventCounts is there and InteractionCounts isn't, is that InteractionCounts isn't supported anywhere yet but EventCounts is. (and so there is BCD for EventCounts and not for InteractionCounts).

Oh, sorry, I didn't check the support.

you have PerformanceElementTiming, but this is a WICG interface. Still, it is already documented. Not sure what to do here or what our general policy is on WICG specs. I suspect we have a lot of them already.

It was already documented and has an implementation, so I think we should care about it.

+1

you are missing PerformanceNavigation and PerformanceTiming

Both are deprecated. I'm happy to add them, but maybe it would be better to discourage them as much as possible?

I think we should add them. Discouraging comes with deprecation. But we need to be consistent either way - this PR adds {{APIRef("Performance API")}} to these pages )(https://github.com/mdn/content/pull/22031/files#diff-f75804c2d8e3509e92e7d6ff6c78e1eb8e2eb431ea2140fa0d8314a62c753b58R20), so they should appear in the groupdata entry as well.

Okay fair enough, I added them. Do you think I should file a yari issue because it doesn't display the deprecated icon in the sidebar for these two under "Related pages for Performance API" ?

You mean for instance in the sidebar at https://pr22031.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/Performance_API/Using_the_Performance_API ?

tbh I think if you actually want it to be fixed, file a PR to do it and I will review it. It looks like DefaultAPISidebar doesn't look at Deprecated etc tags.

okay, will do :)

wbamberg · 2022-11-03T23:09:25Z

files/en-us/web/api/element_timing_api/index.md

@@ -12,7 +12,7 @@ tags:
 browser-compat: api.PerformanceElementTiming
 ---

-{{DefaultAPISidebar("Element Timing")}}{{SeeCompatTable}}
+{{DefaultAPISidebar("Performance API")}}{{SeeCompatTable}}


Eventually we will delete these other overview pages, won't we?

Yes, I would do that as a follow-up once we have a replacement page to redirect to (we don't have it just yet).

wbamberg

👍

Elchi3 requested a review from wbamberg November 3, 2022 11:28

Elchi3 requested review from a team as code owners November 3, 2022 11:28

Elchi3 requested review from bsmth and removed request for a team November 3, 2022 11:28

github-actions bot added the Content:WebAPI Web API docs label Nov 3, 2022

Elchi3 force-pushed the performance-groupdata branch from a616a98 to caf4bc3 Compare November 3, 2022 11:38

Reduce Performance APIs to a single group

2566ccd

Elchi3 force-pushed the performance-groupdata branch from caf4bc3 to 2566ccd Compare November 3, 2022 11:49

wbamberg reviewed Nov 3, 2022

View reviewed changes

Elchi3 mentioned this pull request Nov 4, 2022

OWD project: Update MDN Performance API docs openwebdocs/project#62

Closed

Add deprecated interfaces

185b4fe

wbamberg approved these changes Nov 5, 2022

View reviewed changes

wbamberg merged commit 66c9543 into mdn:main Nov 5, 2022

Elchi3 deleted the performance-groupdata branch November 5, 2022 10:03

Elchi3 mentioned this pull request Dec 6, 2022

Update Paint Timing pages #22771

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Reduce Performance APIs to a single group #22031

Reduce Performance APIs to a single group #22031

Elchi3 commented Nov 3, 2022

github-actions bot commented Nov 3, 2022 •

edited

Loading

wbamberg left a comment

wbamberg Nov 3, 2022

Elchi3 Nov 4, 2022

wbamberg Nov 4, 2022

Elchi3 Nov 4, 2022

wbamberg Nov 4, 2022

Elchi3 Nov 4, 2022

wbamberg Nov 3, 2022

Elchi3 Nov 4, 2022

wbamberg left a comment

Reduce Performance APIs to a single group #22031

Reduce Performance APIs to a single group #22031

Conversation

Elchi3 commented Nov 3, 2022

Description

Motivation

Additional details

Related issues and pull requests

github-actions bot commented Nov 3, 2022 • edited Loading

wbamberg left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wbamberg left a comment

Choose a reason for hiding this comment

github-actions bot commented Nov 3, 2022 •

edited

Loading