Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Revise/expand documentation for description. #226

Open
pixelzoom opened this issue Oct 20, 2024 · 0 comments
Open

Revise/expand documentation for description. #226

pixelzoom opened this issue Oct 20, 2024 · 0 comments

Comments

@pixelzoom
Copy link
Contributor

pixelzoom commented Oct 20, 2024

For https://github.com/phetsims/scenery-phet/issues/876, to serve both PhET developers and the SceneryStack community...

As mentioned in phetsims/sun#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 phetsims/joist#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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants