OWD project: Docs for Web Performance API measurements

[Elchi3]

Problem statement

In 2022/2023 we have overhauled the Web Performance API reference docs on MDN. This was in response to feedback from the Web Performance Working Group in #62.

We created a central place for Performance measurement APIs at https://developer.mozilla.org/en-US/docs/Web/API/Performance_API. All overhauled Perf API reference docs are linked from there.

A few guides have been revamped and added. We haven't written all of them, though. See https://developer.mozilla.org/en-US/docs/Web/API/Performance_API#guides.

Proposed solutions

The Divio system describes a 4-part scheme and has been guiding us to create great sets of documentation (https://documentation.divio.com).
The first part, the reference docs, are done. However, we should complete the guide material, add how-to pages, and add a performance measurement tutorial to give web developers the information they need to instrument and measure the performance of web sites and web apps using standard web technologies independently from 3rd party tools.

Task list

Missing guides:

• Paint timing
• Long task timing
• Largest contentful paint
• Event timing
• Element timing
• Layout shift

How to ...

• Observe performance data
• Collect custom metrics on the client side
• Collect custom metrics on the server side
• Measure FCP
• Measure LCP
• Measure FID
• Measure TTI
• Measure TBT
• Measure CLS
• Measure TTFB
• Sync timings between window and worker contexts
• Set HTTP headers for Performance APIs to work best
• Use the Beacon API to log performance information
• Record rage clicks
• Manage buffer sizes when recording a lot of PerformanceEntry objects
• ... (other practical how-to code snippets)

Tutorials:

• Instrumenting a sample application

Priority assessment

• Effort: ~8 weeks
• Dependencies: SME for the tutorial to create an application with debuggable performance pitfalls
• Community enablement: How-to pages are short pages can be written in parallel by several people including community members.
• Momentum: All browsers implement the majority of the API. A few more specialized APIs are Chromium only for the moment. There is always a lot of momentum when it comes to improving the performance of web apps & sites.
• Enabling learners: The how-tos and the tutorial in particular target learners who want to understand Performance measurement concepts and will enable them to instrument their code.
• Enabling professionals: The Performance API concepts and details are important for professionals who want to debug in depth using the (low-level) standard APIs. It will allow them to go deeper into performance details than it would be possible with 3rd party performance tools. Also, the Perf API standard is also used for APIs on the server-side (e.g. node.js), so learning these concepts will be useful there as well.
• Underrepresented topics / Ethical web: Performance matters on low-end devices and in areas with low-speed internet.
• Operational necessities: N/A.
• Addressing needs of the web industry: Performance comes up in surveys regularly. Might make sense to read https://almanac.httparchive.org/en/2022/performance and other data points for more input on specific needs of the web industry.

More information

Open Web Docs (OWD) is a non-profit collective funded by corporate and individual donations.

In order for this project to happen, please consider donating to OWD on https://opencollective.com/open-web-docs.
For more information on sponsorship and membership tiers, see https://openwebdocs.org/membership/

More information is available at https://openwebdocs.org.
For questions, please reach out to [email protected].