What should be in the explainer?

[alcooper91]

cc @Manishearth

It feels a little weird that we have two documents that are almost the same, but not quite. (e.g. We haven't backported some changes to the explainer and haven't fully written the FakeXRInputController).

Which leaves me the question of what should be in the explainer? Typically it's motivations and such I think, but should we still have actual IDL definitions there?

[svillar]

IMHO the actual IDL definitions should have very limitted presence if any in the explainer. What should be there instead is actual JS code making use of the APIs. My 2c.

[alcooper91]

FWIW, originally the explainer was the only document we had, and the bikeshed was added relatively recently.

[Manishearth]

Yeah I think if we want we can get rid of the explainer, even, or just at a high level say who the consumers of this API are for.

We don't need the explainer if the only users of the API are test writers.

[alcooper91]

I think we need to translate some of the explanations/algorithms about the Input stuff is all?

[Manishearth]

Yep

[Hexcles]

It'd be useful to briefly explain the purpose and rationale for defining the test API (as opposed to e.g. defining a WebDriver extension). The target audience could be both web developers ("Why is this not exposed by default?/Can this be used for testing WebXR applications?") and implementers ("Why do we need a special API to test this?").

[svillar]

It'd be useful to briefly explain the purpose and rationale for defining the test API (as opposed to e.g. defining a WebDriver extension). The target audience could be both web developers ("Why is this not exposed by default?/Can this be used for testing WebXR applications?") and implementers ("Why do we need a special API to test this?").

Yeah, big +1 from my side. Actually the main question I got while my webkit implementation was reviewed was, why it was not defined with a WebDriver API? I pointed reviewers to this issue but it indeed lacks the whole discussion that lead to that decision.

[Manishearth]

I think the reasoning behind this was somewhat ad-hoc, however when we did talk with the W3C testing group they were very much in support of this approach.

[stephenmcgruer]

I think the reasoning behind this was somewhat ad-hoc

I think it is still useful to document whatever reasoning there is. Even if its really just "we've done all this work, so it would be really hard to move it all to webdriver", writing that down allows the community to have honest conversations about it.

If there are more reasons than just that, however, it would be doubly great to have them documented!

[stephenmcgruer]

Some potential background for the road to a test-only API:

immersive-web/webxr#187 originally seemed to focus on a WebDriver approach

#9 is the follow-on from it, which contains some debate as to whether WebDriver should be required or should be an implementation detail. Unfortunately a lot of the discussion that happened 'in groups' is not really captured there.

So it seems like the decision point happened somewhere else...

[Manishearth]

I wasn't around for the initial discussions.

I was there for the meeting at TPAC where the testing group said they liked this approach, @jgraham would you be able to expand on that assessment?

[svillar]

I think the reasoning behind this was somewhat ad-hoc, however when we did talk with the W3C testing group they were very much in support of this approach.

Right, that was the impression I got. Something like Google had something and Mozilla had something similar so let's not reinvent the wheel. But as @stephenmcgruer says, even in that case, adding the rationale of the decision helps others to understand the "why".

[alcooper91]

@Hexcles can correct me if I'm wrong, but I believe (from Chrome's perspective), we opted not to implement it in/via webdriver as we want to run the WPTs on release versions of chrome, and WebDriver would increase our binary size for test-only scenarios.

[alcooper91]

The last remaining changes that hadn't been brought out from the explainer to the actual spec text (index.bs) were ported with #62, so I think the explainer can be completely re-written (or have the more spec-like parts cut out); whenever we get a chance, and otherwise can just be largely ignored until then.