(scribe missed a bit)

Tess: explains a bunch of the first three paragraphs of the explainer, and tries to explain it with different examples.

Rossen: commonly used in AR when you want to augment successfully and persist over time. Naming of the concept is already overloading anchor in HTML.

Tess: I assume it's a term of art in XR. Sort of a name clash for the Web. That's part of the confusion.

David: feels a little like scroll anchoring

Tess: model anchoring

Tess: If they said that -- a method for anchoring XR models to the environment. Started simple, then got more complicated, then it would be clearer.

Tess: I'll look at these minutes and try to distill this into a comment on the design review.

Tess: Who are people writing explainers for? We've talked about this a bunch. I worry people write explainers for the TAG, and come to the TAG to check a box. So they're not writing the explainer to be a useful living document, but instead this one-off thing to get a checkbox checked.

Alice: Do you think we can change this, or need to work with it?

Rossen: change what?

Alice: ... what Tess was referring to, that people write explainers as a one-off document for the TAG, rather than a living document for a general audience including for developers learning the API. Do we need to live with that (I'm not happy to do, it's extra labor for us). This is why I've been pushing back on this for the last year. But if we need to accept that people are writing explainers for us, rather than writing for a more general audience, are we able to do something about this or not?

Rossen: I couldn't agree more. People shouldn't abuse this review, and use this in lieu of standards work (as we discussed already). I guess my point is that something that worked well for some of the previous engagements with API reviews is that we insistent that the equivalent of explainers (that we were using) were intended with the developer user in mind. They were supposed to explain how the feature works, and give code examples that people could use to try it out. Which is how most APIs are done on MSDN. 90% of docs on MSDN are these explainers translated into MSDN. I'd love to see similar rigor here, where explainers would get converted into an MDN doc or into part of the spec that could be taken forward.

Alice: Agreed. I've had this discussion with Joe Medley (tech writer on Chrome team). We want this to feed onto MDN. So we want it to be as close as possible to what that will end up as. How do we get that to happen? The explainer explainer tries to hint at that, but not very explicit. We've tried to keep it brief; don't want people to have to read a whole essay on explainers. Maybe we could tweak it a little. Similarly with issue template -- those are the contact points for people. I think people are familiar with it. I'm not sure what other contact points we have to influence that. (Rossen asks clarifying question) We have limited contact points with people coming to us for reviews -- where we can influence the process. The explainer hints at that, but we also need to keep it brief. If it's too long they'll skip straight to the template.

Rossen: Do we have good examples of explainers that have made it through the process and were used as MDN material.

Alice: Don't know offhand. Maybe we should have a task to research that in a non-issue week.

Rossen: Might motivate people more if people knew their explainer would end up on MDN. The way to incentivize people is to show them it's good for them.

Alice: Does point to underinvestment in communication work in the tech industry. Maybe we can capture this as an issue on design reviews repo. We could capture this as an issue to come back to in a non design review week.

(Alice volunteers Rossen to file the issue against the explainer explainer... and then decides Alice can file issue and assign Rossen and Sangwhan and Tess.)

(Side discussion about explainers that have separate versions in Google Docs and markdown, where the latter is out of date.)

(Alice files the issue.)

Tess will comment on this issue to give feedback on the audience for their explainer

Alice: Left a comment on this one.

Rossen: One of our main confusions was the use of Anchor in the web platform to mean something other than ... anchor :)

Alice: (reads comments) ... Still don't get what Anchor Space is... (reads explainer) and it still doesn't help.

Peter: Anchor == 3d point in space. It can be used to associate a given model with the surrounding space - example, putting a flower pot on top of a physical table.

Alice: If this is really a term of art in 3d I understand but it's still better if they can come up with any other name.

All: discussion on what and how anchorSpace, pose and anchor all relate to each other.

Peter: It will be good to request better example code and use case that readers can visualize and understand for themselves. Alice, can you add comment?

Alice: yes, I'll also comment about the naming of the API. ... also, are we happy with the API? It seems pretty straight forward but there's also lots of missing info about how the API is to be used. ... we still have a problem with the API not explained well in the explainer. How do we explain the API without using IDL?

Peter: I do like having IDL in explainers...

Alice: Ideally the explainer is what you'd see on MDN. ... OK, I'll add request for better example, less IDL and the naming issue

Alice: they haven't responded to questions yet...

Alice: if you've got something on a table and you create an anchor from a hit test result and you move the table around then the object on the anchor moves around...

... And then there's XR Frame ... Each returns a promise. I asked in my feedback why it was a promise. The answer is it might need to ask hardware for it. The API is minimal. The API seems fine.

Yves: Can an anchor be shared?

Alice: Is it serializable? Based on the explainer I would say no.

Yves: wouldn't it be better if it was serializable and have a URL for it?

Dan: I think it only makes sense for one AR session?

Yves: use case would be for sharing a place with someone else... Might be out of scope.

Alice: XRFrame.createAnchor takes a reference space and a pose. I imagine what you'd need to create a duplicate anchor would be the pose, assuming the same reference space.

Dan: it's worth asking.

Alice: can we give them feedback - investigate what the thought process is when people are writing explainers. We get a lot of explainers that are writing with us as an audience. In this case the explainer doesn't seem to be written with us as an audience because it's written with knowledge of XR assumed. It would be interesting to understand - what do they understand the purpose / audience to be?

Dan: we could be more direct. The purpose of the explainer is $this, and the audience is $that. it's in the explainer explainer, as I said to the AC. The audience should be web devs, but those who may not be knowledgeable about your thing. It starts with the user need. This doc could then be adapted to material for this API, like an MDN article.

...We've seen this issue, of assuming domain knowledge, with a lot of other reviews.

Alice: yeah.. with some nuance.. a lot of people have been forced to write explainers because of our process. We have an audience we can encourage to write explainers before they come to TAG. When they ask for a design review it could be too late. We're getting explainers out of the XR group. They're a group that wants to do the right thing. So what's their process given that the intentions are good? Also with this issue I filed about IDL - what can we do to make that process less confusing.

Dan: I'll chat with Ada [group co-chair] about it today.

Alice: Now that I've had it explained multiple times by people - other than Yves's comment... My other question would be are there any other members on XR anchor other than Anchor Space? It seems like it's a holder for the anchor space... In which case why have the XRAnchor at all? Why not have a subclass of XRSpace which would get us out of this naming collision as well

Alice: No update on their end yet

[bumped to the 17th]

Dan: Still waiting on an explainer update.

[bumped]

Alice: they added terminology which I appreciate. The explainer has gotten a lot better.

Dan: Seems like the updated explainer did answer the question.

Alice: This is really good now.

Proposed close.