As mentioned in https://github.com/phetsims/sun/issues/901, ParallelDOM has low-level and high-level APIs that are available to programmers. Low-level APIs are intended for developing reusable common-code UI components. High-level APIs are intended for use in sim-specific code.
interactive-description-technical-guide.md is a nice start as a resource for PhET developers and designers - and possibly the SceneryStack community. But it does not differentiate between the low-level and high-level APIs that are available. For description, almost all of the information in this document is about the low-level APIs, and it is therefore as helpful as it could be for sim developers.
Documentation should be structured to match whatever tiered approach to description is adopted by PhET. Having a tiered approach was discussed in https://github.com/phetsims/joist/issues/985.
The various binder files (AccordionBox.md, ComboBox.md, etc.) suffer from the same problem -- most of the information is low-level API (which is great to have!), and there is an absence of information and examples for high-level APIs. When investigating how to implement description specifications for sims (like in MOTHA) most of what is in the binder files is at the wrong level, and therefore not helpful.
For https://github.com/phetsims/scenery-phet/issues/876, to serve both PhET developers and the SceneryStack community...
As mentioned in https://github.com/phetsims/sun/issues/901, ParallelDOM has low-level and high-level APIs that are available to programmers. Low-level APIs are intended for developing reusable common-code UI components. High-level APIs are intended for use in sim-specific code.
interactive-description-technical-guide.md is a nice start as a resource for PhET developers and designers - and possibly the SceneryStack community. But it does not differentiate between the low-level and high-level APIs that are available. For description, almost all of the information in this document is about the low-level APIs, and it is therefore as helpful as it could be for sim developers.
Documentation should be structured to match whatever tiered approach to description is adopted by PhET. Having a tiered approach was discussed in https://github.com/phetsims/joist/issues/985.
The various binder files (AccordionBox.md, ComboBox.md, etc.) suffer from the same problem -- most of the information is low-level API (which is great to have!), and there is an absence of information and examples for high-level APIs. When investigating how to implement description specifications for sims (like in MOTHA) most of what is in the binder files is at the wrong level, and therefore not helpful.