Re: [w3ctag/design-reviews] WebXR DOM Overlay Module (#470)

I found the introduction particularly confusing because the second paragraph is about not supporting inline AR content, and I couldn't tell how that was related to the first paragraph. It seems like the first paragraph of the introduction is really an "abstract" (a good one!), and then the second paragraph begins a "background" discussion, and then paras 4-6 are more specific use cases. It would be very helpful if it could be more structured to demarcate how the ideas in each paragraph relate to one another.

In general, the level of detail is often too deep, too quickly. For example: 

> The DOM overlay consists of a single rectangular DOM element and its children. 

Very helpful!

> It is composited on top of the immersive content by the user agent. 

Also helpful.

> The application can style the alpha color channel for elements to leave parts of the overlay transparent, but there is no depth-based occlusion.

This is extremely specific - worth mentioning in a details section somewhere, but not necessary in a summary.

> The environment view and 3D elements in the scene are always covered by non-transparent DOM elements, using alpha or additive blending for partially transparent DOM elements as appropriate for the display technology.

Again, this is too much information for a summary (and, I would have thought, mostly implied by the second sentence anyway).

This kind of jumping around in levels of detail makes it very hard to keep track of the high level ideas as we read through. It would be much easier to read if it started with a high level overview and then discussed details as necessary and in the relevant context.

The overview/feature summary could probably mostly be replaced by diagrams or screenshots of examples where the API could be used, with captions explaining the important features (such as DOM content always appearing on top of XR content, and how events are handled).

There are also several cases where points seem to be repeated, e.g. "The DOM overlay is restricted to a single rectangle at a fixed Z depth chosen by the user agent" and "The application does not get low-level control over placement of the DOM overlay; the placement of the overlay is intentionally left up to the user agent."

I suspect that the general concepts involved are relatively straightforward, so a succinct explanation of the general concepts should be possible. More detail can be built on top of that context.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3ctag/design-reviews/issues/470#issuecomment-658002918