The examples.md is hard to follow

[Nancy-Salpepi]

For https://github.com/phetsims/qa/issues/1060, the examples.md is difficult to understand as it is currently written.

Consider separating out the different commands. For example:

Get Statistics for a Field:

The summary statistics for Projectile data can be computed from the Field data by adding commands in the API.

It is first necessary to get the state for a field before computing any statistics. Here is an example using Field 1 on the Variability screen but the process is the same for all fields: let state = await phetioClient.invokeAsync( 'phetioEngine', 'getPhetioElementState', [ 'projectileDataLab.variabilityScreen.model.fields.field1' ] );

Mean Distance Compute the mean of the distances for the landed projectiles using:

Launch Speed Compute the mean launch speed of all landed + airborne projectiles using:

Launch Angle Compute the mean launch speed of all landed + airborne projectiles using:

[Nancy-Salpepi]

I would also add a section on Customization of Mystery Launchers since those phet-io IDs are found in the Global Controls

[samreid]

I wrote some updates here. @matthew-blackman want to review and add anything?

[matthew-blackman]

@samreid I made few changes in the commit that I think make it easier to follow. Can you review?

[samreid]

It looks good to me, even though it doesn't match the exact request from the top comment. Let's consult with @KatieWoe and see what she thinks.

[KatieWoe]

Things look better to me. I'm not sure what purpose the first section serves? Maybe some clarification there?

[matthew-blackman]

Thank @KatieWoe! I added a line to explain the Projectile state object in the first section. Closing.

[matthew-blackman]

Reopening to address feedback from @arouinfar.

[matthew-blackman]

From 4/5 meeting with @arouinfar:

• Update ProjectileSchema list to include all available variables in Projectile state
• Flesh out the 'Customize Launcher' section and move it to the top of examples.md
  • Include discussion of the 'Custom mechanisms'
• Add links for all sections
• 'Preferences' section (See end of https://github.com/phetsims/phet-io-sim-specific/blob/main/client-guide-common/templates/examples-template.md)

[KatieWoe]

From slack during https://github.com/phetsims/qa/issues/1068.

Kathryn Woessner I get this error trying to use the first example in the example doc. Can you help?

Matt Blackman Taking a look.. Looks like a miscommunication. The code in the ‘Projectile State’ section isn’t meant to be pasted into the browser. It is more of a “this is the data structure that is being used to define the projectiles”. Can you recommend a way to convey this so that it’s clear that the ProjectileSchema = {... code is only meant to be a reference? Kathryn Woessner Note: this code is a reference to how the Projectile Schema is defined. To see how to access this data in the browser see some of the following examples. Maybe?

[Nancy-Salpepi]

I'm still a bit confused about the examples.md. @matthew-blackman I'm wondering if any changes were made after @arouinfar's feedback in this https://github.com/phetsims/projectile-data-lab/issues/262#issuecomment-2040279561? In general, I feel like it is written so developers understand it, but maybe not instructional designers.

[matthew-blackman]

@Nancy-Salpepi I'm on the job! Planning to address @arouinfar's feedback in an upcoming commit. Let's plan for a review after RC.1 is complete.

[matthew-blackman]

This has been updated and is ready for review. Thanks @arouinfar!

[arouinfar]

@matthew-blackman the examples doc is looking great! I added the standard Preferences section and made a few other minor edits in the above commit. Please review.

I recommend moving the Customization of Mystery Launchers/Launcher Mechanisms examples to the top of the doc. I like starting with things clients can do in Studio, rather than API examples. They also seem like fairly important customizations you may want to draw attention to, but I recognize that may be a matter of personal style. Feel free to make the change or keep it as-is. :smile:

[KatieWoe]

Things look better in rc.2. I did notice that, for the section on Preferences, you need to have opened the menu to access some of the examples. It may be good to mention this.

[arouinfar]

I did notice that, for the section on Preferences, you need to have opened the menu to access some of the examples. It may be good to mention this.

Thanks @KatieWoe. Each example states, "Note that the Preferences dialog must first be opened." For example:

I confirmed that all Preferences include this statement. Is there something else you recommend?

[KatieWoe]

Nope! If it were a snake it would have bit me. Sorry about that. Closing

[matthew-blackman]

Reopening for final updates to Sampling screen examples.

[matthew-blackman]

The examples.md files for both PDL and PSD have been updated and reviewed by me and @catherinecarter. Nice work! Closing.