Improve the API/scalability for Tier 2 Description

[samreid]

@kathy-phet said:

When implementing description here - please think about the API for Tier 2, and how to make it scalable! This is our chance to work on API improvements in the context of this sim - so we need to take advantage of it - so look at what you are doing there, and decide what kinds of higher level APIs / functions would help.

In today's planning meeting, @kathy-phet said it's important to have the goal: scaling Tier 2.
accessibleName + helpText are easy. But we need that ease for context responses, object responses, dynamic state descriptions.

[samreid]

@jessegreenberg and I met with @terracoda last week to discuss ideas to improve API and scalability for implementing Tier 2 Description. That meeting gravitated toward talking about process improvements that would make things better.

Yesterday @jessegreenberg and I worked on some description, and discussed how the process went and what we could do to scale and simplify the API. We also discussed fluent vs json and how to modularize descriptive text.

[samreid]

I will keep this in mind but will be able to better contribute after we get further implementing some Tier 2 description. I still need assistance getting started with that.

[zepumph]

Today @samreid @jessegreenberg and I discussed this and had a nice conversation about tier1/2 description and fluent's potential involvement in description strings at PhET. It is hard to capture things generally, but I will try with some thoughts below.

• There is no silver bullet to Tier 2 description implementation, it is complicated and requires investment
• The primary challenges are:
  • The code required in mapping model state into natural language
  • Code changes required during iterative design
  • Testing and confirming design complete and no regressions moving forward (while other development occurs).
  • We described Visual output as a "many to many" relationship, where a collection of items in a sim are rendered as that same number of items on the screen. Whereas dynamic audio description output is a "many to one" relationship, because many modules need to be layered into the same aria-live output, and only one thing can be spoken at once. This is challenging because it generally complicates modularity, and increases the chances that something breaks during development. We noted that other parts of description are "many to many", state descriptions in the PDOM and voicing ReadingBlocks for example.
• There isn't one solution that will help us substantially improve scalability, but here were some thoughts we had:
  • Improve the ease of access to strings so that designers can test simple changes as quickly as possible.
  • Increase the percentage of description that is "many-to-many" (instead of many -to-one).
  • Develop description on a component-by-component basis, so that a design can be finalized and thoroughly tests before moving on to the next part of the implementation (help keep things modular).
  • Can we improve modularity with multiple fluent/json string files? This isn't too directly related to the primary challenges above.

I'm sure I'm missing some of our 2 hour conversation, so please fill in details that I missed.