Re: Making sense of the various web performance specifications

On 06/10/2015 10:19 AM, Boris Zbarsky wrote:
> Dear group,
>
> At this point there is quite a number of web performance specifications,
> some of them with multiple draft versions.  They have non-obvious
> dependencies on each other, and making sense of them is _very_
> difficult.  I've seen multiple engineers try to make sense of them,
> fail, and give up and move on to something they perceived as a better
> investment of their time.  This is, of course, not conducive to actually
> getting them implemented, to address Philippe's concern at
> <https://lists.w3.org/Archives/Public/public-web-perf/2015Jun/0052.html>.
>
> I think it may help to do the following:
>
> 1)  Get rid of implicit behaviors in favor of explicit ones.  For
> example, and addressing Philippe's concern again, I _think_ that
> http://www.w3.org/TR/2015/WD-navigation-timing-2-20150604/#processing-model
> steps 2-4 is what's supposed to make
> window.performance.getEntriesByType("navigation") return the relevant
> PerformanceNavigationTiming object.  But that's not at all obvious from
> reading this processing model, nor indeed really stated explicitly
> anywhere; you kind of have to read between the lines of 3 separate
> specifications to realize it(!).  Simply having an explicit "add to the
> performance timeline" step which links to the text that talks about what
> it means to be added to the performance timeline would help a good bit.
>   Assuming I understand correctly how the current setup is meant to
> work, at least, which I'm not more than about 60% sure about.
>
> 2)  An explicit dependency graph between the various specifications
> would be very helpful (whether in the form of an explicit dependency
> listing in each spec or a summary page linked from each spec or
> something).  That would make it clear where to start to disentangle this
> ball of string (e.g. which specifications need to be implemented first
> because other ones depend on them).
>
> In general, the goal should be that it's possible to read a
> specification and have a clear idea of what needs to be done to
> implement it, including which other specifications it depends on and in
> what ways...

This all seems good. We've been doing some refactoring between 
Navigation Timing and Performance timeline 2 or 3 months ago. I also 
need to get the new version of Performance timeline published in /TR, 
otherwise people will keep getting confused by version 1. My goal here 
is to make sure that all versions of our specs, like 
/TR/navigation-timing/, /TR/performance-timeline/ points to the latest 
version in sync with the editors drafts.

One idea we've been meaning to do but never took the time was to rewrite 
Navigation Timing on top of Resource Timing. Right now, there is a lot 
of duplication between the 2 specs and we often forget to keep them in 
sync, which means we have inconsistencies. If we still believe it's a 
good idea, we'll need a volunteer to give it a try.

As a separate project, I meant to produce a version of the webperf specs 
as one single document, to make it either for folks to read and 
navigate, and help us making sure we're consistent. I still need to 
convert some of the specs to respec to facilitate that btw (such as user 
timing). If folks believe it would help a lot, I can try to increase the 
priority of this one on my TODO list.

Re dependency graph, would it be helpful to have a primer document to 
help folks understand how the API fits together?

Philippe

Received on Wednesday, 10 June 2015 15:22:25 UTC