In the keyboard shortcuts dialog, should the basics actions be listed before or after the sim-specific actions?

[samreid]

On Slack, @pixelzoom said:

Question… Is there a reason why the common-code keyboard help content puts the “Basic Actions” on the right, AFTER the less-basic actions? It seems like “Basic Actions” should be on the left, the first thing that left-to-right readers are likely to read. For example, I’m using SliderAndGeneralKeyboardHelpContent in Fourier, and I see this:

@jessegreenberg said:

That's a good thought, I don't know if that was considered

@pixelzoom said:

Worthy of an issue?

@jessegreenberg said:

Sure! I don't feel too strongly either way, though maybe @arouinfar or @terracoda has an opinion. Should be a quick thing to swap if that is best.

@arouinfar said:

It probably comes from older iterations of the keyboard dialog where there was one column for sim-specific interactions and one column for more general things. I think the idea is that folks who use alt input probably already know how to move around, press buttons, etc. We include the basic actions in the dialog because people unfamiliar with alt input may find the keyboard dialog and want to try it out for themselves. I don’t really have a preference for the ordering of the columns.

@terracoda said:

You are right @arouinfar, for efficient non-visual access, it’s best to put the most useful and needed information first. Basic Actions are for people who are unfamiliar with alternative input methods. The sim actions should stay on the left and come first in the reading order. (edited) I think putting the sim actions first is actually best for all users because it’s those actins which are most important to explore.

[samreid]

I decided to open this issue to (a) clarify the design intent and (b) to make sure there is a paper trail in case it comes up again.

My confusion came from the fact that it is not obvious that the section titled "Slider Controls" is about sim-specific actions, as opposed to the other column of basic actions. Also, like @pixelzoom, my instinct was that the basic controls should be listed first.

it’s best to put the most useful and needed information first. Basic Actions are for people who are unfamiliar with alternative input methods.

Is the assumption that people who are familiar with alternative input methods will be the primary users of the keyboard help dialog?

I think putting the sim actions first is actually best for all users because it’s those actins which are most important to explore.

The first entry in the "Slider Controls" section is "adjust slider <- -> ^ v". But a user would need to tab to the slider with a "basic action" first, so it makes sense to me to list that first. If we were going to put the basic actions last, it would seem like they are more of a footnote, but it doesn't seem like they are designed like that. Also, won't advanced users be able to easily skip from the Basic section to the sim-specific section?

Finally, let's discuss the column names and about "this sim" controls vs "all sims" controls? What if we wanted to add another sim-specific control to the pictured sim, but it is not a "Slider Control"? Would there be another column or another section in that column?

Likewise, is the "Slider Control" code factored out? I see 3 occurrences of that string across our repos. This part could be moved to a side issue. Is it easy for a new sim to include "Slider Controls" and other sim-specific controls?

[jessegreenberg]

What if we wanted to add another sim-specific control to the pictured sim, but it is not a "Slider Control"? Would there be another column or another section in that column?

I think there would be another section in that column. The dialog used in BASE has a column with two sections


"Slider Control" code factored out?

Yes, SliderKeyboardHelpSection exists in scenery-phet.

For the ordering, I don't feel strongly enough to cast a vote but would be fine changing it if there is an agreement that is best. So removing my assignment until we hear from others.

[samreid]

For the sake of discussion, I created a mock-up that swaps the sides:


[terracoda]

Just an FYI, "Slider Controls" comes from the Interactive Description Design. It's not a general heading for the column. The heading is meant to be sim specific.

In Ohm's Law and Resistance in Wire, the sim actions are prominent sliders, and are named Slider Controls in the State Descriptions of the PDOM. In GFLB (and GFL) the sim actions are Move Spheres and Change Mass because that is what the learners need to do.

And some sim-specific actions are custom interactions, like in BASE. That is, actions that learners, even advanced screen reader and keyboard users would not be able to guess. These custom interactions often come with handy shortcuts, too. We don't want people searching for instructions. We went them using the sim.

The layout of the Keyboard Shortcuts dialog has been through 100's of interviews. It works really well for blind learners.

I have less data on learners who can see, but we made a really nice addition, the "Tab to get started" line when a young learner (without self-identified disabilities) explored the Keyboard Shortcuts dialog in a general interview. This learner then tried to execute the instructions (started hitting the left and right arrow keys) without moving her focus to an actual interactive object. This curious young learner even asked about how the controls were suppose to work.

The "Basic Actions" heading and the content under it has been vetted by the team already.

I'm not opposed to changes, but I do not think the layout needs changing. We have made other minor changes over the years (ones mentioned above) and others...making sure focus starts at the top, making sure the heading is read out nicely to start, etc.

The layout has never been brought up by learners. I think having "Tab to get started" near the top and then sim actions described first ensures learners can quickly find the help they need and then get back to interacting with the sim.

[terracoda]

Thanks for the mock-up Sam, but imagine you cannot see, and you need to read through line by line all the interactions you already know how to do before you get to "Grab or Release Balloon".

Even for visual readers. It's nice to know what's important. Important stuff comes first.

You tab and then you play with the balloon.

[terracoda]

I am so glad the team is asking questions about this stuff. It helps share the knowledge.

[zepumph]

It sounds like there has been discussion about this, and it has been explained why the design was made the way it was (sim-specific/most important interactions first). Can we close this issue?

[samreid]

Everything seems good to me, I think the issue can be closed. Anyone please feel free to reopen if there is more to discuss.