search

ddbeck / common-web-feature-mockup

1 stars 1 forks source link

Add Performance API groups #6

Closed Elchi3 closed 1 year ago

Elchi3 commented 1 year ago

Hey @ddbeck, here is my 30 minutes exercise to create groups for the Performance API docs that Open Web Docs is working on right now.

I don't know if a group can be subtracted from other groups but if you would want relevant Performance APIs, it would be "performance-apis" minus "deprecated-performance-apis".

Of course, more groups are possible here. I'd love to know what would be performance-apis.2022.json. Would I check what is supported in all 3 engines as of today and create a group from that?

Elchi3 commented 1 year ago

An assumption I've been working with is that each group would have a flat list of constituent features. I noticed that you listed top-level interfaces, but not deeper than that (I'll flag what I mean in a line comment).

Was this a shorthand on your part (so you didn't have to fill out a giant list)? Or did you expect that interfaces would be automatically searched?

Hm, yes, I think I was think the queries are like api.Performance.*. Of course, if I had spelled out all features, it would have been more work but then I could have left out the deprecated members, too, if I wanted.

I step through each feature and check to make sure there's three implementations for each.

OK, yes, I think this would be a good exercise. I guess that this will create more groups and separate the initial performance API implementation from new additional feature sets, e.g. User Timing level 3, PerformanceObservers, etc.

First, on the authoring side: suppose you could've entered in the relationship between performance-apis and deprecated-performance-apis. Where would you have expected to note this? As part of the constituent features (e.g., flagging a query somehow)? Or somewhere else?

I guess I would want a thing that is called parent-group or similar to note that there is a (kitchensink) group where this belongs to.

Second, what about the output semantics? Suppose we calculate the support of performance-apis minus deprecated-performance-apis. Which of these scenarios make more sense to you: deprecation as part of a chain, deprecation as a branch, or deprecation as an island? Or something else? See the illustrations below.

I think it would make sense to me as a branch. The parent group "performance-apis" is the group for all performance api groups no matter what. "performance-apis-2022" is a group that contains features of all "performance-api" groups that are implemented in 3 engines in 2022 and it doesn't contain features of the group "deprecated-performance-apis".

ddbeck commented 1 year ago

Hey @Elchi3, thanks for replying to this—I've been thinking a lot on what you've said. I've started work on code that actually processes a simple case (ingesting a flat group with no parent-child relationships and producing a summary from it). This is a really helpful thing to have now, so I'm going to merge it and see what I can do with it, functionally. Thanks again!