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?

[zepumph]

I'm not sure what's best. I don't want to add a big step in an already large checklist before we really know what the best workflow is, because we are still figuring it out.

@terracoda, here is a draft about the protocol with documenting these a11y interactions in the style guide md files:

1. If there is an abstracted js file for the a11y interaction (like AccessibleNumberTweaker.js):
   • Make sure that there is a paralleled AccessibleNumberTweaker.md file in the "proper place" (see appendix A below) in the doc folder for the repo.
   • Make sure that any common code component that uses this pattern has a PERMANENT link to this document, i.e. point to github.com master (see appendix B below).
   • Organize this markdown file as the same content/header structure as what would be included as the a11y portion of the main common code markdown file (see appendix C below).
2. If there is no abstracted js file for the a11y interation:
   • Simply put the a11y interaction content in the common code md file directly.
   • @terracoda already has a very solid format for how this should look.

Appendix:
A. By "proper place" I mean that the doc director should hierarchically look exactly the same as the js dir. So any js file under js/buttons/*.js should have a markdown file in doc/buttons/*.md.
B. Later on @mbarlow12 can work with this basic solution and improve on it, but there is a lot of other stuff to be done right now, so I don't want to bother him.
C. By keeping content the exact same (even if that means starting with h4 level headers), it may make integration into the style guide later easier.

I would love to have majority consensus on this approach, since it seems pretty big to the style guide moving forward. Tagging @amanda-phet @samreid @jessegreenberg @mbarlow12 @terracoda provide suggestions in comments below OR react to this comment with something stating their feelings.

[samreid]

Sounds great, but can you please provide an example of

has a PERMANENT link to this document, i.e. point to github.com master (see appendix B below).

[jessegreenberg]

#11 (comment) sounds great @zepumph.

[zepumph]

Sounds great, but can you please provide an example of

has a PERMANENT link to this document, i.e. point to github.com master (see appendix B below).

https://github.com/phetsims/sun/blob/master/docs/accessibility/AccessibleSlider.md

[samreid]

Is that superior to https://phetsims.github.io/binder/accessibility/AccessibleSlider.md ?

[zepumph]

It is easier. as the link doesn't have to be processed on build to point to binder's version (and binder has to copy it over on build too).

@samreid your link seems like a nice step 2 improvement.

Step 3 to me would be to load that markdown, and the parse it with the marked library we are using, into HTML, and then add it directly to the style guide. I was laying out what I thought of as the simplest idea.

[terracoda]

@zepumph, I think this is sounding ok. The heading hierarchy of the content in the md files is important, so I agree if an md file is part of some other documentation, I (or the writer) will need to make sure the heading hierarchy remains consistent.

[terracoda]

@zepumph and @samreid, I just came across something a little different for the Accordion Box pattern. There are two js components that are used to create the full experience:

• ExpandCollapseBar.js - this seems to be an Accordion Header (the functional title bar if you will)
• AccordionBox.js - this seems to the be an Accordion Panel (the content that is hidden or revealed by the associated Accordion Header)

For the general and accessible design documentation, I don't think it makes sense to separate them. They seem like they would always go together.

Is this same issue as the issue? Or a different issue?

[samreid]

Assuming for the moment that AccordionBox used ExpandCollapseBar, we should still have ExpandCollapseBar.md and AccordionBox.md. In that case you would document it by saying "AccordionBox uses a ExpandCollapseBar to show the title", with a hyperlink to ExpandCollapseBar. Then if other clients just use the ExpandCollapseBar, without using AccordionBox, the documentation would still be accurate.

However, looking in the implementation of AccordionBox, it appears it does not use ExpandCollapseBar at all.

Either way, we would still document each file separately with its own .md file. That makes our process simpler, straightforward and composable.

[terracoda]

I can link to the PhET components in the docs. Perhaps there should be a section near the top listing what components are covered by the documentation.

[mbarlow12]

@zepumph This seems like a good way to move forward for now. It will also be useful to find a way to automatically generate some kind of flag or reference when these cases arise

[zepumph]

Right, like a templating var perhaps

[zepumph]

Let me know if you need any more help.

[zepumph]

In this morning's a11y meeting, we decided that for right now, we will treat VerticalAquaRadioButtonGroup.js and RadioButtonGroup.js as the same, without different md files for accessibility. Do I have that correct?

[ariel-phet]

Removing @samreid assignment for now

[terracoda]

The examples and design patterns in these 2 tip sheets that I created for the Description Design Course (2022) may be an example of a more general alternative for documentation, rather than doing the design pattern PhET component by PhET component.

• Tip Sheet - Design Patterns for Single- & Two-State Interactions
• Tip Sheet - Design Patterns for Multi-State & Customized Interactions

In my documentation, I refer to "Interaction Types" and then leave the documentation to define the exact details of interaction.

For example, here's the design pattern for a toggle interaction, of which there are many sub types...

{{button name}}, button
Accessible Name:
Interaction Type: toggle button, two-button toggle, on/off switch, other
States: e.g., selected or pressed/ not pressed; on/off
Initial State: pressed or not pressed
(Optional) Help Text:
(Optional) Context responses or link to section with context responses.
(Optional) Design Note: Special things about this toggle button, if any.

Here's the design pattern for a slider interaction...

{{Name of slider control}}, slider
Accessible Name: An action-oriented name if possible.
Interaction Type: slider
Orientation: horizontal or vertical
Slider values/positions (states): describe what the slider is representing in quantitative and/or qualitative terms. Sometimes sliders use both qualitative and quantitative terms.

• Examples:
  Range: provide min and max values of the slider.
• Initial value/position:
  Step Sizes:
• Default step size (with Arrow keys):
• Larger step size (with Page Up & Page Down keys): max range/10
• Smallest step size (with Shift modifier key):
• Jump to min Home key (min position/value):
• End key (max position/value):
  (Optional) Help Text:
  (Optional) Design Note: Special things about this slider, if any.
  (Optional) Link to section with object & context responses

[terracoda]

Un-assigning myself from this issue until we have time to discuss this further.