How to handle the same a11y documentation for different components

[zepumph]

From phetsims/sun#361, I see a need for single a11y documentation (like interaction pattern and sample html) to document AccessibleSlider.js. But that file is mixed into many different common code types (and more to come). Currently the way that binder is set up, we are generating documentation by component, because of the way that InstanceRegistry is set up.

I think the best way to proceed is to have a single component md file that has this content, and then in all the other files, we point to the one saying, "a11y interaction is the same as {{base-component}}." So in Faucet.md you will be pointed to HSlider, since it is the same interaction. This will also be good to do with RadioButtonGroup vs VerticalAquaRadioButtonGroup.

[samreid]

Maybe clearer to add AccessibleSlider.md, then have both HSlider and Faucet point to that?

[zepumph]

From an implementation standpoint, that seems to me like we would have to (a) parse files to determine what mixins they use, or (b) somehow detect that during runtime. Both of those seem gross to me, do you have any other thoughts @samreid?

[samreid]

The documentation HSlider.md would have a manually-written section that reads:

HSlider gets its accessibility features from AccessibleSlider.md (hyperlinked). Here are some more specific things HSlider adds above and beyond that...

[zepumph]

Well, when you put it that way, it seems really nice. Is there anything automated involving AccessibleSlider.md?

[samreid]

I think that part should be manual. The automatic part will track which sims use Faucet and HSlider, the documentation will manually refer to AccessibleSlider.

[terracoda]

@samreid, I like your idea of Accessible{InteractionName}}.md. I was thinking along the same lines, but in the reverse direction (links in the md file to the actual covered js components, or comments in the top of the js file).

I think this will work just fine from the accessible documentation side of things.

[zepumph]

That seems like a good first step. One possible improvement that we could do, would be to somehow mark the a11y links in the main markdown files, perhaps with templated vars on either side, and then load that a11y markdown into that spot in the main markdown.

Example

HSlider would look like:

## General Design
* blag

## Accessibiliy
{{template}}See [AccessibleSlider.js](github.com/phetsims/scenery-phet/js/AccessibleSlider.js){{template}}

Then on build that file get's put into the Accessibility section for HSlider, as well as any other common code type using that a11y interaction.

[terracoda]

@zepumph if you look at the RadioGroup.md file would you say that everything under

## Accessibility Considerations

down to the end would be in a separate MD file?

[zepumph]

Very good question! Currently radio button groups have two PhET implementations:

• RadioButtonGroup: arbitrary nodes/images that have radio button functionality (like coil selection in FL)
• VerticalAquaRadioButtonGroup: Looks like html radio buttons stacked on each other.

Currently their implementation is different in terms of a11y, and there is no talk of separating out that functionality into their own Accessible{{Interaction}}.js mixin. Although I would defer to @jessegreenberg because maybe I have missed something.
My recommendation would be to put that content into the markdown for RadioButtonGroup.js (so RadioButtonGroup.md) for now.

To clear up some confusion from this morning, we were naming accessible markdown files, to be linked to by the main markdowns, but I was only recommending that strategy for places where that pattern exists in the code. So currently that would only apply to AccessibleNumberTweaker and AccessibleSlider. As we create more of these a11y interaction mixins, then the documentation can be refactored too. What do you think?

[jessegreenberg]

there is no talk of separating out that functionality into their own Accessible{{Interaction}}.js mixin. Although I would defer to @jessegreenberg because maybe I have missed something.

I agree, less straight forward to use mixin pattern here because instrumentation is required on the button group and the individual buttons. But we could look into it, depends on implementation of RadioButtonGroup and VerticalAquaRadioButtonGroup.

My recommendation would be to put that content into the markdown for RadioButtonGroup.js (so RadioButtonGroup.md) for now...As we create more of these a11y interaction mixins, then the documentation can be refactored too.

I agree. Would be a good way to refactor documentation, but difficult step to remember. Maybe we should add a step to the common code review checklist to do this?