What to call "descriptions" features

[zepumph]

Over in phetsims/scenery#997 @jessegreenberg and I are interested in renaming code from "accessibility" to be more feature specific. For example, a file that holds all the model data for a Node in the PDOM used to be called Accessibility.js, and we want to rename it to PDOM.js. This is in an attempt to move accessibility work to a more "feature-specific" understanding/documentation/implementation.

Part of this discussion was coming up with some broader terminology about what we mean when we say "descriptions" or "full descriptions" or "dynamic descriptions"

Something that @jessegreenberg and I came up with was calling it Interactive Descriptions. Here was @terracoda's response to our thoughts, see phetsims/scenery#997 (comment):

@zepumph, in phetsims/scenery#997 (comment) you posted:

The feature that has been a large part of scenery descriptions, and accessibility implementation in sims shall henceforth be known as "Interactive Descriptions." This feature is comprised of the following three sub-features:

• Description support (PDOM Content) -> Supported by PDOM -> Implemented by Accessibility.js
• Alternative input -> Supported by PDOM -> Implemented by Accessibility.js/Input.js
• Interactive alerts -> Supported by aria-live -> Implemented by UtteranceQueue.js

I'm wondering if it is worth discussing the terms a little more. I literally just finished a paper describing the refined description design framework and the terminology has evolved a little bit.

In terms of design, we now have two main categories of description, and the each have 2 types of descriptions:

1. State Descriptions - accessed on-demand by the user
   a. Static States
   b. Dynamic States
2. Responsive Descriptions - delivered automatically upon activation and interaction
   a. Object Responses
   b. Context Responses

I'm wondering if it might be prudent to have a conversation about exactly what is meant by "Interactive Descriptions" and "Interactive Alerts". Perhaps "State Descriptions" and "Responsive Descriptions" covers it?

Tagging relevant parties for discussion. Perhaps we will want to meet and discuss synchronously.

[jessegreenberg]

Thanks for the feedback @terracoda, that all makes a lot of sense. Conceptually, I think that the list we made with "Description Support", "Alternative Input", and "Interactive Alerts" could be replaced with your terminology and I think that is great.

One thing we were looking for is a term for all of these things together. And for this, we are proposing "Interactive Descriptions" . So with your terminology, it might look like
State Descriptions + Responsive Descriptions = Interactive Descriptions

What do you think?

[zepumph]

One thing we were looking for is a term for all of these things together.>

Right! Perhaps this is just the feature called "Descriptions" composed of State Descriptions + Responsive Descriptions. or "Interactive Descriptions."

I don't really see a focus on alternative input in the paper. Here are a few more thoughts about adding that to the mix:

• Maybe Alternative Input is another feature altogether. With this in mind perhaps we just say that sims like Molarity and GFLB were published "with Descriptions and Alternative Input". Some more examples:

  • Coulombs law was published with "Alternative Input"
  • Some sims have "State Descriptions and Alternative Input"

• Perhaps we want Alternative Input to be combined into the description-related feature. In which case we may have:

  • State Descriptions + Responsive Descriptions = Descriptions
  • Descriptions + Alternative Input = Interactive Descriptions

I'm sorta shrugging over here. It's a lot of semantics and I don't feel very strongly about any of it.

Again my goal is to just be able to have a single word/phrase that describes the feature set that is being implemented in Molarity/GFLB currently. Personally I like the ring of Interactive Descriptions. Descriptions and Alternative Input is okay too.

[terracoda]

Oh shoot, I commented in the other issue
phetsims/scenery#997 (comment)

without seeing the above comments from @zepumph and @jessegreenberg.

Reviewing now.

[terracoda]

@jessegreenberg, my only concern with your equation in #145 (comment)

is that most "Responsive Descriptions" are supported by aria-live and implemented by UtteranceQueue.js , but some Responsive Descriptions (e.g., Object Responses for sliders) I think would be implemented by Accessibility.js/Input.js

The terms I posted above work well for our design process. I like the terms "Interactive Descriptions" and "Interactive Alerts". Our sims are indeed interactive! If we break things down more like I did in the other issue, do you think these terms would work for developers in general?

Interactive Descriptions

• static state descriptions
• dynamic state descriptions
• object values deliverable through aria-valuetext or some similar PDOM-embedded method.

Interactive Alerts

• context responses
• object responses when there is no PDOM-embedded method for delivery.

I think for the website categories (simple description, full description) we might have to leave as-is for now. They are supposed to simple for public consumption.

[terracoda]

@zepumph and @jessegreenberg, am I right to think that "Alternative Input" can actually not include any description?

[zepumph]

After a meeting with @terracoda and @jessegreenberg today, we came up with the following. The feature/sub-feature is named, and then in parens is the technological implementation name. We also reached out to @emily-phet and she was in agreement.

Interactive Descriptions:
	State Descriptions (PDOM)
		a. Static States
		b. Dynamic States
	Responsive Descriptions 
		a. Object Responses (UtteranceQueue/PDOM/Both)
		b. Context Responses (UtteranceQueue)
	Alternative Input:
		keyboard (PDOM)
		mobile (PDOM)
		switch (PDOM)	

Closing

[jessegreenberg]

We received some feedback from the team that "Interactive Description" was confusing.

It started with confusion that ?supportsDescriptions enables both keyboard navigation and descriptions. But in general, people felt that "descriptions" don't accurately describe all of the input/output that comes with this feature set. We were hoping that "Interactive" would describe the input part of alternative input + description. But @pixelzoom said

"Interactive" here is an adjective being applied to the noun "Description", an output. There is nothing here that clearly communicates "input" to me, it's fuzzy.

"Alt-iO" was suggested, and has a branding tie to "PhET-iO".
?supportsPDOM was also suggested as a more technically accurate query parameter.

I wondered if ?supportsInteractiveDescriptions, would also be a more descriptive query parameter but it doesn't address the root of confusion.

Reopening to discuss again with @zepumph and @terracoda and @emily-phet.

[terracoda]

Who are the query parameters for?

[pixelzoom]

@arouinfar also pointed out that "Interactive Description" is public-facing on the PhET website - it is one of the a11y filters on the Filter page.

But I don't think that choosing terminology (or query parameter name) should be overly-concerned with whether it's internal or public-facing. I'd hate to see us say "this is good enough for internal use". Clear terminology promotes good communication, internal terminology has a way of leaking out into the world, and any terminology (good or bad) is difficult to change once it gets established.

[terracoda]

"Interactive Description" is a term, an intentional term.
It is not an adjective and a noun.
It is not "interactive descriptions (plural)".

Personally, I am really happy with the term, and I do not understand what the confusion is.

[ariel-phet]

Hey all, saw this discussion on dev public.

@terracoda totally understandable to not understand the confusion. I think @samreid also had some thoughts here, maybe he can summarize better since he started the discussion on the public dev channel. Let me ask him to chime in.

[samreid]

Thanks for pointing me to this issue, it's helpful to see the summary definition of Interactive Description in #145 (comment).

I had some more questions about how this pertains to phetsims/wave-interference#412. If I understand correctly, our plan is to publish Wave Interference with keyboard navigation but without State Descriptions or Responsive Descriptions. How can this be accomplished? Will specifying "supportsInteractiveDescriptions": true in package.json turn on the descriptions, but they will be buggy because they are incomplete?

Also, the only aspect of Interactive Description that doesn't indicate it is powered by the PDOM is Responsive Descriptions -> Context Responses (UtteranceQueue), but isn't the UtteranceQueue powered by aria-live on the PDOM elements? I can understand if the goal was to come up with a name for the feature set that isn't locked into an implementation detail, but I wanted to understand that the PDOM is currently instrumental in each aspect of Interactive Description. Correct me if this is wrong.

It was confusing to specify ?supportsDescription to turn on keyboard navigation. ?supportsInteractiveDescription might have made sense if the definition in #145 (comment) had the qualifier "one or more of the following features" (and if I had been aware of this definition).

@arouinfar also pointed out that "Interactive Description" is public-facing on the PhET website - it is one of the a11y filters on the Filter page.

Our clients will not be aware of our definition, and they are likely to read that as "adjective noun" as others in this thread have. I don't know of a better term, but it may be unclear to include the term "Interactive" since PhET simulations are already interactive without PDOM-related features. The top line of this issue is:

Over in phetsims/scenery#997 @jessegreenberg and I are interested in renaming code from "accessibility" to be more feature specific.

Is "Interactive Description" more feature-specific? What if we add other accessibility features that fall outside of the definition in #145 (comment)? Will we expand the definition or come up with an additional query parameter?

On Mac, the System Control panel describes "Accessibility" as "Accessibility features adapt your Mac to your individual needs. Your Mac can be customized to support your vision, hearing, physical motor, and learning & literacy requirements". I suspect other OS's use similar terminology. How does this match the goals of our project? Is there a roadmap of more accessibility features PhET wants to support in the future, and how "Interactive Description" relates to that larger picture? Specifically, what features does "Interactive Description" not include that we hope to add later?

[zepumph]

In terms of implementation, there is no granularity between alternative input and description. If you turn one on, you turn all on. We named Interactive Description (as a thought out and designed terminology) to describe this encapsulating feature set. The accessibility team has implemented and published multiple simulations with keyboard navigation but little/no static/response description. In these cases (molecules-and-light, coulombs-law), using those published simulations with a screen reader may give you an idea of how tied the two features are in terms of implementation.

I understand that the query parameter is not totally clear, but I think that it is important to think of it as a single, large feature set. I have mentioned this issue of "incomplete" description in the past when working with a simulation solely on alternative input, and there was not a lot of momentum to spend time stripping out content in those cases. I agree. What would be the benefit in spending energy reverting partial description back to its default, "black box" state for screen readers. Energy should be spent in outfitting and adding features to simulations.

If it would be easier to remember, we could create an alias for ?supportsDescriptions like ?alternaitveInput, but note that they are one and the same as scenery is concerned.

RE:

Will we expand the definition or come up with an additional query parameter?

and

Is there a roadmap of more accessibility features PhET wants to support in the future, and how "Interactive Description" relates to that larger picture?

There are already many other a11y features that have their own channels. Haptics output, sound output, tangible input, self voicing. Each of these are being worked on separately, and thus have their own controlling flags/ query parameters. Thus Interactive Description is just one of many.

[emily-phet]

Hey folks - is there a blocking issue here? If not, let's discuss later in the year.

My guess is that what is needed here is a meeting of interested folks where we lay out the interconnected set of a11y features, and how some have complex relationships with each other. I understand how these relationships can be confusing, and that it takes learning about these relationships - and considering the implications of these relationships from multiple angles - to get a good handle on them.

We want everyone to ask their questions, have a good discussion, and reach an understanding...but this summer is a difficult time to do that. Let's postpone that process if at all possible. We really need to focus only on mission-critical issues right now.

[jessegreenberg]

I think it would be ideal to talk about this sooner if possible. The meeting would also review the name "Interactive Description" and give interested people an opportunity to make sure this is the best brand name for this set of features. If we wait longer we will become more invested in the terminology we are currently using.