Improve documentation for accessibility-related features

[zepumph]

Interactive Description and other features developed by the a11y team are beginning to get adopted by the team in general greenhouse gas and eating, exercise and energy are both sims coming up this year that will have interactive description in them.

The first place to start is to make sure our documentation about this all is up to date. I will take a first pass as a quarterly goal. This includes:

• [x] https://github.com/phetsims/phet-info/blob/master/doc/how-to-add-accessible-interactive-description-to-a-sim.md#L1-L0
• [x] scenery/doc/accessibility.html
• [x] https://github.com/phetsims/phet-info/blob/master/doc/accessible-design-patterns.md
• [x] Looking through common description types to update jsdoc wherever possible.

[zepumph]

This is a quarterly goal right now, raising priority

[zepumph]

In scenery/doc/accessibility.html, I made it to "PhET Specific Information" I think that section should be completely moved out into the "how to add accessible interactive description to a sim" doc.

[zepumph]

• [x] Write a note in the phet specific doc about the possibility of the "pdom heading" higher level feature, even though it doesn't exist yet. Ask devs, if they would like this feature, to reach out as desired.

[zepumph]

Summary of work thus far:

• how-to-add-accessible-interactive-description-to-a-sim.md renamed to interactive-description-technical-guide.md
• accessible-design-patterns.md deleted and in-lined into the technical guide
• PhET specific stuff moved over into the technical guide.

Still TODO:

• Check boxes above
• [x] Discussion about screen summary/play area/control area, and their Nodes in each ScreenView

[zepumph]

We are now ready for a review. @jessegreenberg please take a look first through the scenery accessibility documentation. Likely this needs larger work because it only talks about the PDOM as a feature, but it seems like a good start for now.

Next look at the Technical Guide. As thorough of a read through as you feel you have time for would be very helpful to progress project-wide understanding of ID as a feature.

Thanks!

[jessegreenberg]

This is all really great @zepumph, nice work. Here are the notes I took that may be worth considering. Starting with accessibility.html since reading that is a prerequisite for the technical guide.

accessibility.html

• /scenery/doc/accessibility-implementation.html is not complete but may not be useful anymore. Should it be completed or maybe just deleted now?
• In the "Multiple DOM Elements per Node" section... This goes into a lot of implementation detail about siblings and peers, and I wonder if it is too much since it is one of the first examples we are showing. What do you think about replacing all of the content above the Example in this section with something more simplified that introduces the options like

  The basic example shows one DOM element representing a Node in the PDOM, but ParallelDOM.js supports a richer HTML structure. Each Node can have multiple DOM elements. To be represented in the PDOM, the Node must have a primary element specified with tagName. It can optionally also have a label element specified with labelTagName, a descriptions element specified with descriptionTagName and a structural container element specified with containerTagName.

... then show example?

• The "Focus" section goes into a lot of detail about aria roles and input which may be more clear in another place, maybe we should remove info not related to focus.

interactive-description-technical-guide

• In the "What does Interactive Description Mean" section...This list is great, but it may not be clear what each of these are. Can we define them here?
• "Implementing Interactive Description" section...This includes a note about documenting options but is mostly a list describing some the most used features of ParallelDOM.js. There is also a line "This is where you are piecing together all of the individual nodes.", I am not quite sure what this means. What do you think about changing this section to "Web Accessibility Toolkit" that includes info about accessible name, aria-labelledby, aria-valuetext, aria-live, role, aria-label, label. It could then conclude with "for many other features of web accessibility see {{link to third party source}} and {{link to ParallelDOM.js}}."
• The "Interactive Alerts" section shows utteranceQueue as a singleton to import, was that intentional?
• The "PDOM Order for PhET Sims" section... Sorry, I don't understand number 5, how is that different from number 2?

Between the two

• The Techical Guide starts by introducing features and terminology, and accessibility.html goes right into code examples. Would it actually be better to start with the technical guide and then direct to accessibility.html?
• I am curious about the relationship between accessibility.html and the technical guide, do you think they should be combined? I noticed some slight overlap between the two. For example, the section on adding an input listener in the technical guide seemed like it might fit in an accessibility.html example.

[zepumph]

I am curious about the relationship between accessibility.html and the technical guide, do you think they should be combined? I noticed some slight overlap between the two. For example, the section on adding an input listener in the technical guide seemed like it might fit in an accessibility.html example.

I think that this is a really good point. My hope would be that the two documents have very distinctive differences. I want the scenery doc to be just about implementing the features, and the technical guide to be used as a "best practices" document. It is likely that they both still need a fair amount of work to get there.

[zepumph]

Other review comments have been done.

[zepumph]

I made it through review comments, but I'm still unsure about how much more I can do to further divide the two documents up. I would like to do much more! It may require some design time for me to sit down and think about a structure for both.

[jessegreenberg]

I made a change related to this to organize a11y docs so that other pages can be added. Under scenery/doc there is a new accessibility folder, and it now has "accessibility.html" and "voicing.html", and others can be added in the future.

[jessegreenberg]

In https://github.com/phetsims/scenery/issues/1241 @pixelzoom said

Finally... If you plan to writeup any developer instructions for hotkeys, it would be good to highlight the global nature of globalKeyStateTracker listeners, the importance of checking pdomDisplayed, and the importance of expression ordering for the if statement that short-circuits handlers. I don't know if such a doc is planned, so I'll leave that it up to @jessegreenberg whether/how to address documentation.

A section about global hotkeys would be great to add to this document so noting this here as part of this issue.

[zepumph]

@jessegreenberg do you still want to add a global hotkey section to the doc?

[pixelzoom]

Maybe global hotkeys should be defined in a source code file? External documentation will probably get stale.

It would also be bonus if something could error loudly if you try to use hotkey that's already used globally.