Consider deprecating primer

[nicjansma]

We've previously published this: https://w3c.github.io/perf-timing-primer/

However, it's likely a bit stale and out-of-date. We don't actively put any energy in maintaining it.

Would it be better to publish into a section of e.g. MDN?

[bdekoz]

Bummer. This is very useful information, and I was just referencing this during today's discussion about resource timing discovery time...

Given the uncertainty shown today about where/when serviceworkers might interact with RT, I'd rather fix it. Is this what you mean about "stale and out-of-date"? I think another alternative would be to put all the timing diagrams for web perf in one doc (say primer) and remove them from Nav Timing 4.1 Process Model, etc, pointing here instead?

[bdekoz]

This came up curing all-Mozilla standards review, and the suggestion is to remove section 8, and move to publish this as a Note. With those changes (and updates for service workers?) keep in-charter?

Mozilla position is that these (non-normative) diagrams are good and a useful explainer for this group, and existing copyright allows them to be reused by vendors in other places/context like MDN.

[yoavweiss]

The main problem with this primer is that it wasn't actively maintained over the years (and hence contains some inaccurate info - e.g. RE the FrameTiming effort which was since abandoned). Would Mozilla be interested in updating this primer and maintaining it?

MDN does seem like the right place for this kind of information, and a place where it might get some more traction in terms of maintenance. I wonder if it won't make sense to invest effort in moving it there.

^^ @Rumyra for thoughts on the above

[nicjansma]

@yoavweiss and I discussed and we'd like to keep the Primer in the 2023+ charter, with the goal of modernizing it a bit first.

Some suggestions:

• Adding sections for APIs that are new since the original Primer was written:
  • Event Timing
  • Paint Timing
  • Device Memory
  • Long Tasks/LOAF?
  • Beacon
  • Reporting/NEL? (we could also link to its existing Explainer)
  • Page Visibility? (moved to HTML)
  • Element Timing + LCP (incubation)
  • Layout Instability (incubation)
  • Performance Observer should get more attention (and maybe a suggestion to use it over Performance Timeline), showing options like buffered: true, etc
• The current document is very measurement-focused. Do we add a section for developer performance controls such as:
  • Resource Hints (moved to HTML)
  • Preload (moved to HTML)
  • Priority Hints (moved to HTML)
  • Scheduling APIs (incubation) / requestIdleCallback (published)
  • is-input-pending (incubation)
• Removing sections that are no longer relevant (e.g. Frame Timing)

This work could be done by WG members and/or Mozilla folks if desired. We would like to get it into a good enough shape that it could be considered for possible inclusion in something like MDN.

Two main questions I have driving the above updates:

• Do we discuss any specs only in incubation? That would include some commonly-used APIs like ElementTiming/LCP/LayoutInstability.
• Do we discuss any specs we've published a previous draft for, but have since moved to HTML?

[nicjansma]

Added a note in the charter draft of planned work: b452d75

[tunetheweb]

Reopening this after discussion at TPAC 2024 and TPAC 2025.

The latest feeling IIUC is that the Working Group is not the best place to maintain these docs. We don't prioritise keeping it up to date. Whereas MDN and other resources like web.dev ARE actively maintained.

MDN has the following docs:

• https://developer.mozilla.org/en-US/docs/Web/Performance
• https://developer.mozilla.org/en-US/docs/Web/Performance/Guides
• https://developer.mozilla.org/en-US/docs/Web/Performance/Guides/Navigation_and_resource_timings
• https://developer.mozilla.org/en-US/docs/Web/Performance/Guides/Rum-vs-Synthetic
• And also have lots of details in the individual API docs.

MDN is open source and community contributed.

Additionally other resources like web.dev have these docs:

• https://web.dev/articles/user-centric-performance-metrics
• https://web.dev/articles/custom-metrics
• https://web.dev/learn/performance
• And lots of docs on Core Web Vitals in particular.

Web.dev is closed source and maintained by Google. Which is not ideal, but they are also the ones driving a lot of these APIs. (Note that I work for Google!).

Additionally we discussed at TPAC 2025 the scope of what the Web Perf WG should cover, and how usage of these APIs (e.g. for INP, and Core Web Vitals in general) are not necessary under the purview of the Working Group.

I've reviewed the current primer and don't think there's anything in there that is not already covered (often better) by the above resources.

Mozilla position is that these (non-normative) diagrams are good and a useful explainer for this group, and existing copyright allows them to be reused by vendors in other places/context like MDN.

I don't think this is a concern, since the main useful diagrams are for Performance Navigation Timing and Resource Timing, both of which are in the respective specs (here and here respectively) so are already covered by those specs in terms of existing copyright and allowing reused vendors in other places/context like MDN (in fact I've updated these diagrams in MDN multiple times and they are MUCH more up to date in there, than on this primer!).

We should continue to follow that model going forward for any new useful diagrams. Though not really seen newer specs do that (nor need to?).

Given all that, I think we should remove this from the charter (as we agreed to at TPAC after this review) and add a note to the spec pointing people to other resources like MDN and web.dev (I think the like is important here).

Keen to hear if you all agree with this?

CC also @davehunt who I've also discussed this with.

Note I think the other other deliverables in the charter have important privacy and security guidance and so need a separate discussion (gut feel is they still belong in the WG, but not looked heavily), so this is just talking about the Primer for Web Performance Timing APIs document.

[Bas-moz]

I agree with your assessment and we support doing this.

[yoavweiss]

Thanks for looking into this. I'm supportive!