search

phetsims / scenery

Scenery is an HTML5 scene graph.
MIT License
54 stars 12 forks source link

Problems with documentation of options accessibleName and helpText. #1661

Open pixelzoom opened 1 week ago

pixelzoom commented 1 week ago

For https://github.com/phetsims/models-of-the-hydrogen-atom/issues/67 ...

I attempted to learn about accessibleName and helpText from the documentation for those options in ParallelDOM.ts:

  accessibleName?: PDOMValueType | null; // Sets the name of this node, read when this node receives focus and inserted appropriately based on accessibleNameBehavior
  accessibleNameBehavior?: PDOMBehaviorFunction; // Sets the way in which accessibleName will be set for the Node, see DEFAULT_ACCESSIBLE_NAME_BEHAVIOR for example
  helpText?: PDOMValueType | null; // Sets the descriptive content for this node, read by the virtual cursor, inserted into DOM appropriately based on helpTextBehavior
  helpTextBehavior?: PDOMBehaviorFunction; // Sets the way in which help text will be set for the Node, see DEFAULT_HELP_TEXT_BEHAVIOR for example

Problems:

If those problems were fixed, I'd also say that this documentation is inadequate to get me up to speed on these options. It would be nice if they pointed the reader to more details. But no such detailed documentation currently exists... which will be the topic of another GitHub issue.

Assigning to @zepumph based on what git history tells me.

kathy-phet commented 1 week ago

Reassigning this issue to @jessegreenberg, as this is aligned with Jesse's work at the moment.

@jessegreenberg @marlitas - Shall we start a Monday.com triage board around dev:description issues in common code repos, so we can triage and progress?

marlitas commented 1 week ago

@kathy-phet yes I think scheduling triage for description is great. Do we want this board to be separate from the alt-input board? I see some issues in the alt-input board related to description which seems to indicate overlap between the two.

jessegreenberg commented 1 week ago

Shall we start a Monday.com triage board around dev:description issues in common code repos, so we can triage and progress

Yes please! The alt input board has been helpful. I think it will be separate enough to have its own board. Some items that are on the alt-input board could move to a description board.

I'll take a look at the documentation here.

marlitas commented 1 week ago

Great! I'll get one going today and find a time for us to meet. I'm assuming the following people should be involved in the meeting: JG, JO, TS, BF, KP, (EM if available)

kathy-phet commented 1 week ago

@marlitas - @pixelzoom will be adding recommendations based on review and @jessegreenberg will also likely add issues from the prototyping work around translation this iteration, so we won't set up a meeting until those issues are in. My current thinking is meet end of this iteration or early next iteration to scope out the list and set priorities for next iteration.