Making sense of the various web performance specifications

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...

-Boris

Received on Wednesday, 10 June 2015 14:19:34 UTC