OWD project: Update MDN Performance API docs

[mmocny]

A small group of engineers spent about 30 minutes reviewing existing Performance API and Performance Timeline documentation to search for any opportunities for improvement.

We found many examples of improvement opportunities:

For example:

• Lack of a general "Performance Guide"
  • Perhaps can borrow from the explainer with some updates?
  • Perf APIs primer should perhaps be turned into an MDN page.
• Issues in references pages:
  • e.g., In PerformanceObserver reference the description for observe() method does not match the descriptions from the actual observe() method reference page. Both descriptions could use updates.
  • e.g., LCP, ElementTiming, and others do not describe the inherited attributes from PerformanceEntry even though their semantic meaning is specific to the API in question.
  • e.g. PerformanceLongTaskTiming reference is basically empty.
• Issues with Examples throughout reference pages.
  • e.g., dictionary options passed to PerformanceObserver.observe() use entryTypes instead of type and buffered.
• Certain APIs are labeled experimental when they should no longer be (example PerformanceObserver)
• Some new experimental apis are not documented, while some long abandoned apis are still documented (e.g. Frame Timing).
• Various "see also" links are out of date (example)

We think improvements in this area would be very valuable, and greatly appreciated!

[mmocny]

I'll add, several Web Performance WG members have already expressed interest in helping further (for e.g. reviewing pull requests, or consulting on content).

[Elchi3]

Hey @mmocny and everyone who helped filing this proposal! I'm very sorry (and embarrassed) it took so long to come back to you! I have two good news for you all, though!

1. A few issues you mention above have been addressed in the meantime already.
2. We are spending some time on this project in Q4 2022 now, given there were enough votes this time! (unlike in previous rounds, sorry again).

[Elchi3]

Event Timing documentation work

As a first step, I started to take a deeper look into the Performance API docs, starting with the Event Timing specification (not specific reason for this one, it looked small enough to get into the topic). It would be fantastic if you could give some feedback on these docs as it might inform how to best renovate all the other Perf API docs.

GitHub references a few PRs above but let me summarize the Event Timing API work as of now:

• I restructured the main interface page: https://developer.mozilla.org/en-US/docs/Web/API/PerformanceEventTiming
  • Notable is the "Events exposed" table. This was a plain list before.
  • The description section has been expanded to give a better idea about this API. It would probably be good to have a guide about Event Timing that is more like a tutorial. Will come back to this when we have a better idea about where and how to do the general "Performance API guide".
  • Listed the inherited properties from PerformanceEntry as you've proposed above, does that look good?
  • Created the missing subpages (review welcome)
  • The only experimental API here is interactionID, this is per our policy when a feature is in just one engine.
• durationThreshold is now documented on https://developer.mozilla.org/en-US/docs/Web/API/PerformanceObserver/observe
• Added a page for https://developer.mozilla.org/en-US/docs/Web/API/Performance/eventCounts and the EventCounts map.

Above you say,

• e.g., dictionary options passed to PerformanceObserver.observe() use entryTypes instead of type and buffered.

The examples on the Event Timing pages use entryTypes, is this discouraged? If so, I'm happy to use type and buffered here and on other pages going forward.

Is there anything else we miss about Event Timing specifically? Is this summary helpful for you to provide reviews? Let me know! (If you or others want to join our slack or want to get in touch otherwise, my email is [email protected])

I will continue with another Perf API spec and let you know how it goes in a similar post :)

[Elchi3]

Structural work

As a second step in this project, Will (@wbamberg) and I had a look at all the Performance API specs and we think that it makes sense to present them all together as a unified thing in the docs.

Right now you have things like:

• https://developer.mozilla.org/en-US/docs/Web/API/Paint_Timing_API
• https://developer.mozilla.org/en-US/docs/Web/API/Largest_Contentful_Paint_API
• https://developer.mozilla.org/en-US/docs/Web/API/Performance_Timeline
• (and others)

These pages create no coherent picture but rather make it look like these are all very separate APIs. We think it makes sense to redirect these pages to a main Performance API overview page and talk about all these topics as if it was one API (web developers don't particularly care which spec defines which performance measure, they rather want to know what is possible to measure and how).

We updated the main https://developer.mozilla.org/en-US/docs/Web/API/Performance_API page for that. The page now also contains a diagram showing how all the Performance APIs plug into PerformanceEntry. If you have any thoughts about it, let us know. Above, a "Lack of a general Performance Guide" is mentioned. We think it makes sense to install such guide under this main Performance_API page and no longer have the "Using .." pages cluttered around. Stay tuned for that to happen.

https://github.com/mdn/content/pull/22031 will also update the sidebar navigation, so all Performance API pages will be navigable consistently and point back to the main Performance_API overview page and the general performance guide (which we will create).

We also created a spreadsheet to assess every single Performance API page's quality, to decide what can be redirected where, and which new pages we might need to create. https://docs.google.com/spreadsheets/d/1ROfmuMkNUxW7YbuQXdNLnoHDYZseQtjfLSvZ1Qq2Lto/edit#gid=0

Let us know, if you have any feedback about this :)

[Rumyra]

This sounds awesome 👍

[wbamberg]

See also https://github.com/mdn/content/issues/4713.

[robnyman]

Adding in @addyosmani here who might have thoughts/a good perspective on this as well.

[Elchi3]

To give an update: We have updated about 150 MDN reference pages that talk about the various Performance APIs and modernized the code examples with the initial feedback in mind and more. We also presented the APIs as one group as talked about in my comment above. Now https://developer.mozilla.org/en-US/docs/Web/API/Performance_API is the main landing page. For details about the revamping of the Performance API pages, see the ~45 linked pull requests above. Thanks to Will and others who did reviews and provided feedback. I'm also happy to answer any questions and am happy if there is still more feedback for us to look into.

We still have to:

• Update the performance.now and DOMHighResTimeStamp pages, but these are complicated. See https://github.com/mdn/content/issues/4713 for what needs doing.
• Update the various guide pages into a single coherent Performance API guide. It means revamping all the pages that are currently under "Guides" in the sidebar:
  • https://developer.mozilla.org/en-US/docs/Web/API/Performance_API/Using_the_Performance_API
  • https://developer.mozilla.org/en-US/docs/Web/API/Navigation_timing_API
  • https://developer.mozilla.org/en-US/docs/Web/API/Navigation_timing_API/Using_Navigation_Timing
  • https://developer.mozilla.org/en-US/docs/Web/API/Performance_Timeline
  • https://developer.mozilla.org/en-US/docs/Web/API/Performance_Timeline/Using_Performance_Timeline
  • https://developer.mozilla.org/en-US/docs/Web/API/Resource_Timing_API
  • https://developer.mozilla.org/en-US/docs/Web/API/Resource_Timing_API/Using_the_Resource_Timing_API
  • https://developer.mozilla.org/en-US/docs/Web/API/User_Timing_API
  • https://developer.mozilla.org/en-US/docs/Web/API/User_Timing_API/Using_the_User_Timing_API These are still old and guide pages for newer Perf APIs are missing entirely. I'll make a plan for a new guide.

[Elchi3]

I'm going to close this as done! Thanks for all the feedback everyone. A follow-up project for guides, how-tos and a tutorial is described in https://github.com/openwebdocs/project/issues/157.