Create a Quickstart Guide for alternative input.

[pixelzoom]

The need for a Quickstart Guide for alternative input was discussed at 10/21/21 dev meeting.

Since I just added alternative input to Geometric Optics, I'll throw together a rough guide, while it's fresh in my mind.

[pixelzoom]

Draft commited at https://github.com/phetsims/phet-info/blob/master/doc/alternative-input-quick-start-guide.md. This is the process that I developed for Fourier, then used (yesterday) for Geometric Optics. I was able to add alt input to Geometric Optics in < 2 hours using these steps.

Assigning to @jessegreenberg to have a look, to make sure there's nothing blatantly wrong here.

[zepumph]

Thanks so much for this @pixelzoom. This is a subset of the epic defined over in phetsims/scenery#1298

[zepumph]

This is a really great start. I have two thoughts.

• Focusable is not required for a tagName of button because that is already, be default in the browser, focusable. Thus you don't need this line

  phet-info/doc/alternative-input-quick-start-guide.md

  Line 53 in 2b932b9

  focusable: true

  .
• In general I'm trying to figure out how much this document should set us up well for add description. Right now, given these steps, there are some larger refactorings that would need to occur to add description. Mostly because items getting added to the PDOM will eventually need to be organized (with pdomOrder) into the "Play Area" and "Control Area". Although the feature is "alternative input," the PDOM, and the description-capabilities it come with, are still there, and available to screen readers. We have to decide how much we want to treat alternative-input as a "quick and dirty" implementation of these PDOM practices vs the prudence in aligning with the patterns we use to support description. This is both for as consistent of a product as we can have, no matter the feature, and also for limiting the technical debt needed to add description on top of alternative input when publishing Interactive Description.

[zepumph]

Another thought

• No matter what we end up calling these features, the interactive-description-technical-guide.md is the source for a lot more alt-input details, perhaps it would be good to have a last comment linking to that document.
• We should also make sure that anyone reading this document has at least read through http://localhost:8080/scenery/doc/accessibility/accessibility.html (the general PDOM documentation).

[pixelzoom]

@zepumph said:

Focusable is not required for a tagName of button ...

Removed from the Guide in 17bcb18.

• In general I'm trying to figure out how much this document should set us up well for add description. Right now, given these steps, there are some larger refactorings that would need to occur to add description. Mostly because items getting added to the PDOM will eventually need to be organized (with pdomOrder) into the "Play Area" and "Control Area". ...

So far (Fourier, Geometric Optics), I've been instructed by designers to ignore "Play Area" and "Control Area". See for example phetsims/fourier-making-waves#53 (comment). That has implications for setting the ScreenView pdomArea, because you can't set this.pdomOrder for a ScreenView. The workaround is to create a "root Node", which I've been calling screenViewRootNode, add all children to screenViewRootNode, and set screenViewRootNode.pdomOrder. This is not mentioned in the Guide.

I agree that eventually we'll need to addChild to pdomPlayAreaNode and pdomControlAreaNode. But we'll also need to set pdomPlayAreaNode.pdomOrder and pdomControlAreaNode.pdomOrder, since we've previously established that it's not good to couple rendering order and traversal order (except for LayoutBox).

I also do not see this as requiring "larger refactorings".

No matter what we end up calling these features, the interactive-description-technical-guide.md is the source for a lot more alt-input details, perhaps it would be good to have a last comment linking to that document.

I've added this to "Other Resources" at the bottom of the Guide.

We should also make sure that anyone reading this document has at least read through http://localhost:8080/scenery/doc/accessibility/accessibility.html (the general PDOM documentation).

This is already mentioned as in the Prerequisites section of interactive-description-technical-guide.md, so I don't see a need to duplicate that (and the instructions for how to build it) in this Quick Start Guide.

[pixelzoom]

In the above commits, I described the 2 patterns for specifying traversal order at the ScreenView level. See step 4. I also added a link to "Play Area" and "Control Area" description in the Other Resources section.

@zepumph please review.

[jessegreenberg]

This document is excellent, thanks @pixelzoom. All looks correct. The only thing I could think of to add was a note about hotkeys and avoiding collisions with other global hotkeys (with a reference to #188 where we should have a registry for this).

Closing.