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

So the TAG looked at this for about 20 minutes in our breakout just now, and we were struggling with the explainer in various ways:
* It's quite long, and has quite a few pages of text before giving any concrete examples.
* At the same time, it starts off assuming that the reader knows a good bit about the space already.
* It doesn't give the necessary context around the examples that it does give.  For example, when we were discussing the [two images](https://github.com/immersive-web/dom-overlays/blob/master/explainer.md#implementation), participants in the discussion disagreed about which parts of the images were the DOM overlays.  For example, in the first one, I thought the overlay was the bit at the top with text from "Barebones WebXR DOM Overlay" down to the "Exit AR" button, but reading the text made others think that the green rectangle was the overlay.  I couldn't find any text in the explainer to show that my interpretation was correct other than reading the full source code of the example.
* the discussion about connections to the fullscreen API was confusing; it wasn't clear to what extent it was talking about a specification notion of fullscreen elements versus actually displaying something to fill the entire screen.  (I don't *think* either of the two screenshots shows an overlay that is fullscreen... but then again, maybe I was wrong about which part of the screenshot is the overlay.)

We suggest revisiting the [tips for effective explainers](https://w3ctag.github.io/explainers#tips-for-effective-explainers), and perhaps also other parts of that document.

An explainer that is difficult to read makes it hard for interested members of the web community to understand what you're proposing and to provide useful feedback.  These include the TAG.  Given today's discussion, I think it's likely that the TAG wouldn't review this proposal with the explainer in its current state.

(I think @hober and @alice are going to add some more specific questions as well.)

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