Rename "Parallel DOM" to "Accessibility DOM Subtree" or "Semantic DOM Subtree"

[samreid]

Everyone on the PhET team is familiar with the term "Parallel DOM" also shortened as "pDOM", but this term could be confusing or misleading for newcomers or outside groups. Parallel DOM gives the impression that it is a complete Document Object Model, or somehow outside of the DOM, which is inaccurate. It also raises the question of what it is parallel to and doesn't give any indication what it is for (in a sense the graphics subtree is also a "parallel DOM" in that it is parallel to the accessibility subtree). In the documentation https://bayes.colorado.edu/dev/accessibility/accessibility-challenges.html#parallel-dom it is also referred to as an "Accessibility Tree". The DOM specification uses the term "subtree" for that kind of thing, so that seems an appropriate term: https://dom.spec.whatwg.org/

In order to be more clear in the future, we should transition to using a more specific and accurate phrase, such as

• Semantic DOM Subtree
• Accessibility DOM Subtree
• Semantic HTML DOM Subtree

I know the phrase "Parallel DOM" is already propagated to several places, including publications and it will be difficult to change, but it will be even more difficult to change if we wait.

Regarding naming it "Semantic" vs "Accessibility", I'm not sure which is preferable: the former is a better description of what it is and somewhat more general, the latter is a description of what we intend it to be used for.

[terracoda]

just tagging @emily-phet.

[terracoda]

The term, Parallel DOM has been in use with our project for a full 3 years now.

The Parallel DOM offers a parallel experience. It is robust and interactive and conceptually (added), it is not subordinate to anything or embedded inside anything. It's structure and content is fully exposed to assistive technology.

I do not think "subtree" fully describes the power of the PDOM.

The "Accessibilty Tree" is something different.

[samreid]

I understand your objection to "subtree", but I don't understand why the word "Parallel" would be preferable to "Semantic" or "Accessible", which are inherently more descriptive and meaningful.

[jessegreenberg]

Thinking about this more, I think "Parallel DOM" is a good description of what this is technically and works well in the accessibility community. While the browser only creates one DOM, thinking of subtrees of HTML as a separate DOMs is common. One example is the "Shadow DOM" specification. Another is the "Sub DOM" recommendation for accessible fallback content in a canvas.

The "Parallel DOM" is an alternative to "Sub DOM", where instead of "Sub"/"Fallback" DOM content inside the graphical elements, we create "Parallel" DOM content that is parallel do the graphical elements. I worry that calling it "sub" tree/DOM will be overloaded and make it seem less novel.

We met another group that used a similar solution for accessibility, they called it the "UpsideDOM".

When presenting to others we haven't seen this as a point of confusion so I think we will lose more than we will gain by renaming.

[samreid]

I haven't heard any arguments against "Semantic DOM" or "Accessible DOM" yet.

The argument for using "parallel DOM" as an alternative to "sub DOM" makes the most sense to me of all the arguments in this thread.

But referring to it as the "Parallel DOM" still gives a sense that the "main" or "primary" DOM is the graphical one, and the semantic DOM is "parallel" to the primary DOM. Wouldn't it be better to think of the semantic DOM as the primary one, and the graphical DOM as "parallel" to it?

It's fine with me if "Parallel DOM" is indeed the best name--I just wanted to rule out the possibility that we chose it somewhat arbitrarily and never took the time to think it through and change it (if necessary).

[emily-phet]

Seconding @terracoda and @jessegreenberg - there are reasons to avoid some of the suggested alternatives, we've not had any difficulty with people misunderstanding our current use of Parallel DOM (after extensive use for years and wide discussions across diverse groups), and additionally, we've already published about this approach using the current name.

I don't think anyone is arguing this is the 'best' name, but it has historical use, is better than many, and would indeed likely cause more confusion than provide benefit in certainly the short term and possibly the long term. So, let's stick with what "Parallel DOM".

[samreid]

From the slack dev-public channel today:

Chris Malley 11:27 AM

Personally, I’ve never liked the term PDOM. For anyone who doesn’t know what a DOM is, it’s sort of confusing. For anyone who does know what a DOM is, it’s an oxymoron - by definition, any web page has exactly one DOM. (edited) But I see from https://github.com/phetsims/a11y-research/issues/101 that the discussion is closed.

Jesse Greenberg 11:32 AM

I disagree somewhat, for example sub-DOM is another relatively well known method of making an HTML5 canvas accessible, and would be recognized by accessibility/web devs.

Chris Malley 11:32 AM

Distinction between sub-DOM and DOM.

Jesse Greenberg 11:32 AM

There is a specification called the "Shadow DOM" which is an encapsulated DOM within the DOM tree.

Michael Kauzmann 11:33 AM

@pixelzoom you may find this thread good to look at if you haven't seen it. https://github.com/phetsims/a11y-research/issues/101 Oh oops, sorry You have seen it.

Chris Malley 11:34 AM

Yep.

Michael Kauzmann 11:34 AM

Particularly https://github.com/phetsims/a11y-research/issues/101#issuecomment-389236842

Jesse Greenberg 11:34 AM

Distinction between sub-DOM and DOM. Then there is a similar distinction between PDOM and DOM.

Chris Malley 11:41 AM

Not a fan of “shadow DOM” term either. Imo confusing terminology because it conflicts with existing (standard) terminology. But if we repeat it enough, we forget that, and we still manage to communicate. Sorry to bring it up again.

Sam Reid 11:41 AM

@pixelzoom what do you think might be a good name?

Chris Malley 11:41 AM

Not surprising that the first Google hit for “shadow dom” is “What the Heck is Shadow DOM?” (edited) “Parallel” says nothing about accessibility, so if we ever need to use a similar “parallel dom” approach for something else, then we’re cooked.

Sam Reid 11:43 AM

“perpendicular DOM”

Chris Malley 11:44 AM

“Accessibility DOM Subtree” (from https://github.com/phetsims/a11y-research/issues/101) is the most accurate, but doesn’t have the same “ring” to it.

[pixelzoom]

The above Slack discussion was in the context of which prefix to add to PDOM-specific Nodes that have been added to JOIST/ScreenView as part of https://github.com/phetsims/scenery-phet/issues/381. I initially suggested 'a11y', because that prefix is heavily used elsewhere. @samreid suggested 'Maybe the prefix would be “pdom” instead of “a11y” based on considerations in https://github.com/phetsims/scenery/issues/997 ?' Prefix 'pdom' was ultimately used, see https://github.com/phetsims/scenery-phet/issues/381#issuecomment-547563528.

[terracoda]

An important thing to understand from a user experience perspective is that this beautiful piece of architecture - no matter how it is implemented - provides a parallel experience for learners who access it!

The interactive modalities are delivered in parallel. I feel that this parallel-ness is what makes this architecture so innovative!

Edited for clarity after posting.

[terracoda]

@samreid and @pixelzoom, I have had comments like, "Am I using the same sim as a visual student would use?"

We can proudly say yes to this question!

[pixelzoom]

No question about the value of the end result or parallel-ness of the experience, great stuff. Just pointing out some warts on the technical side of things -- namely the dissonance with standard HTML terminology, and "parallel" can be related to things other than accessibility.