Revisit query parameters and package.json entries related to supported and designed features.

[pixelzoom]

Related to phetsims/models-of-the-hydrogen-atom#67 and https://github.com/phetsims/scenery-phet/issues/876 ...

In phetsims/joist#985, we discussed having a tiered approach to description features, with "levels of description". If that's the case, PhET may want to revisit the approach to enabling description features.

In package.json, there is currently one entry under "simFeatures" that turns all description features on/off. From initialize-globals.js:

    /**
     *
     * Enables interactive description in the simulation. Use this option to render the Parallel DOM for keyboard
     * navigation and screen-reader-based auditory descriptions. Can be permanently enabled if
     * `supportsInteractiveDescription: true` is added under the `phet.simFeatures` entry of package.json. Query parameter
     * value will always override package.json entry.
     */
    supportsInteractiveDescription: {
      type: 'boolean',
      defaultValue: !!packageSimFeatures.supportsInteractiveDescription
    },

With only a single entry, it's not possible to turn off work that is not completed or not ready for production. For example, MOTHA has a complete alternative input implementation, but an incomplete implementation for accessible names and help text. If PhET wishes to publish MOTHA with alternaive input, but turn off description, there is no way to do that.

PhET might want to have package.json entries (and associated query parameters) that correspond to the description tiers. For example, "supportsAlternativeInput", "supportsStateDescriptions", "supportsResponsiveDescriptions" (or whatever matches the eventual tiers).

[marlitas]

Meeting 11/19

• supportsInteractiveDescription turns on the PDOM which in turn allows anyone to access alt-input, description, etc. whether it has been designed or not.
• We believe that adding entries that communicate the different tiers would be useful for website and management metadata, but may be confusing to developers if they believe other things are actually getting turned on when it's more like a flag to indicate it has been thought of and designed.
• These recommended names match query parameters and that is intentional. Any changes should update query parameters as well.
• We may want to add a supportsUISound as well in this case.
• We should take this discussion to dev meeting to see how devs feel about this change in approach to simFeatures in package.json
• If we decide not to do this in package.json it would be nice to have this information in the code rather than relying on updating metadata manually on the website.

[jessegreenberg]

This was discussed today during developer meeting -

Developers had two concerns:

1. There is concern that publishing sims with incomplete features (as described above) is not acceptable.
2. It would be confusing if the package.json entries do not accurately describe the implementation. For example, a supportsAltInput flag, which would enable the PDOM and therefore ALL related features like all tiers of description features).

For 1, we discussed that our philosophy has been that "something is better than nothing". We do not advertise or claim to support features that are incomplete. Adding gates to the implementation is not trivial and possibly a significant amount of work. A compelling counterpoint is an example: If a sim gets part way through a "tier 2" description implementation but must be published rapidly (for a PhET-iO client, for example), there is no way to disable the partial "tier 2" feature set. Overall, devs are OK with the way it is, as long as there is an understanding that if there is a complaint about partial feature support, we will not make changes. And we will not remove features in the sim code. We want to make sure that all of this is acceptable to project management.

To ensure that "something is better than nothing", we should do screen reader testing on sims that support any tier of interactive description to verify nothing is broken or inaccurate.

For 2, we brainstormed an alternative where this metadata lives in a different spot. Like a designedSimFeatures in package.json

    "designedSimFeatures": {
      "interactiveDescriptionSupport": 'tier-1',
      "soundSupport": 'ui',
      "phet-io": 'premium',
      "supportedRegionsAndCultures": [ /*...*/ ]
    },

This separates the design categorization/metadata from the fields needed for implementation. In this example, we also brainstormed string values instead of several new Boolean fields.

Ill update data for this issue in our Monday board so that we revisit it again as a team.

[terracoda]

For number 1, people can fill gaps in information - all of us do it all of the time. People with disabilities are particularly adept at problem solving when gaps present themselves.

A sim with some sounds and some description means fewer gaps exist, and leaves it to the learner in their context to determine what they need to fill the gaps that still there.

I feel it is important to leave available information available, rather than requiring a learner to fill all the gaps until the day we publish a fully complete feature.

For number 2, to me it makes sense to ensure that at the time of publication the package.json mirrors the designed features set that is outlined in the sim design doc? Is that what people are suggesting?

[marlitas]

Discussed during Description / Voicing planning and we decided we would like to move forward with the following example:

    "designedSimFeatures": {
      "interactiveDescriptionSupport": 'tier-1',
      "soundSupport": 'ui',
      "phet-io": 'premium',
      "supportedRegionsAndCultures": [ /*...*/ ]
    },

The exact values still need to be refined.

We also confirmed that "something is better than nothing" for description and are okay with sims publishing features that have not been fully vetted. It does not seem useful to isolate parts of the pdom to control publication.