Update query parameters in Teacher Tips

[arouinfar]

In phetsims/query-string-machine#52 we made some changes to the Customization Options section of the Teacher Tips to better explain how query parameters are used, provide more support to translators, and add common code query parameters (like locale and initialScreen) that are supported by all sims.

The next steps are to propagate these changes to existing Teacher Tips documents. For now, the focus should be on Teacher Tips that already include query parameters. Once this work is completed, we can evaluate the needs and process for adding the Customization Options section to Teacher Tips that don't already have it.

Relevant Links

• Updated teacher tips template - sim-name-guide.pages
• Teacher Tips are kept in the associated sim folder under PhET Files > PhET Sim Design
• Tracking spreadsheet (start with sims that have query parameters in the teacher tips)

Checklist

• Download the .pages file located in the sim folder (linked above) and update spreadsheet status to "In Progress"
• Update the date in the footer as recommended in Update query parameters in Teacher Tips #963 (comment)
• "For example, in Collision Lab" section: Update sim name and create an appropriate link.
  • If this is a single-screen sim, use other supported query parameters. If there aren't two supported query parameters, contact a designer.
  • If the URL extends to a 2nd line, reduce the font size.
• "To run this in Spanish" section: Use the same link as above, but add locale=es to the beginning of the query parameters in the URL.
  • If the URL extends to a 2nd line, reduce the font size.
• If the simulation does NOT have a Preferences dialog, delete the cog icon and "Indicates this customization can be accessed from the Preferences menu within the simulation" above the table. Additionally, delete the cog icons from the locale and colorProfile table entries.
• Simulation-specific query parameters should be at the top of the table, followed by common code query parameters.
• Update "Examples" column title to "Example Links" (if using existing table in the doc)
• Update all example links to use the all version of the sim. (Existing examples likely point to the en version.)
• Include only the relevant common code query parameters.
  • screens and initialScreen apply to all multi-screen sims
  • locale and allowLinks apply to all sims.
  • supportsPanAndZoom is supported by all sims tagged with Pan & Zoom on the website
  • Sims with a black background usually support colorProfile=projector. If you find a sim that supports projector mode (from Options menu) but the query parameter doesn't work, it likely supports the deprecated projectorMode query parameter instead.
  • Newer sims with the audio toggle button in the navbar should support audio. Older sims may instead use the deprecated sound query parameter.
• locale query parameter: Update the "Translations tab" link to point to the correct sim.
• If necessary, rearrange sections like "Insights into Student Use" or "Complex Controls" so that the page breaks fall in a better place. The new Customization Section can be very large, so try to start this section near the top of a page or arrange it so that the page break doesn't happen mid-table.
• Once all changes are made, save the .pages file with the same filename.
• Export the PDF at "Best" quality, again keeping same filename.
• Upload the .pages and .pdf files to the sim folder on SharePoint. When prompted, select "Replace". SharePoint will preserve the older versions (click the three dots next to the filename and select "Version history").
• Update the spreadsheet status to "Ready for Review" to indicate the document is ready for spot-check
• When the status changes to "Reviewed - Ready to Upload" the document is ready to upload to the website.
• After uploading the teacher tips to the website, set status to "Uploaded to Website"

Note: based on phetsims/query-string-machine#52 (comment) there may be some further changes to the template, so I'll self-assign this issue. I'll reassign to QA when we're ready to proceed.

[arouinfar]

The template doc has been updated, so this is ready for QA. Assigning @kathy-phet and @KatieWoe for prioritization.

[arouinfar]

QA has completed the first phase of updates. I spoke with @Nancy-Salpepi and here are some next steps:

• Tips Ready for Review: @KatieWoe and @Nancy-Salpepi can review each other's work. Things to check:
  • Verify that the links work as expected
  • Double-check that all appropriate common code query parameters were included
  • If questions arise, reach out to a designer.
• Once the above review is completed, the Teacher Tips are ready to upload on the website.
  • Go to Admin > Simulations > sim name (make sure it is the HTML5 version)
  • Scroll down to find Teacher's Guide section, and upload.
• Phase 2 will focus on sims that don't have public, sim-specific query parameters.
  • Use the Phase 2 tab of the tracking spreadsheet.
  • For each sim, go to the appropriate sim repo and open the js > common directory and look for a query parameters file, for example: https://github.com/phetsims/ratio-and-proportion/blob/master/js/common/RAPQueryParameters.ts
  • If no such file exists, check the appropriate common repo (e.g. circuit-construction-kit-common) or parent repo (e.g. gas-properties). If there still isn't a query parameter file, mark that sim as a "No".
  • If there is a query parameter file, search for the word "public". If there are any hits, mark that sim as a "Yes". If there aren't any hits, mark it as a "No".
  • Sims marked as a "No" only have common code query parameter support, so follow the process outlined in Update query parameters in Teacher Tips #963 (comment). Sims marked as "Yes" will be addressed in Phase 3.

[arouinfar]

Thanks @KatieWoe @Nancy-Salpepi for filling out the Phase 2 tab. Looks like the only sim marked as having sim-specific query parameters is Equality Explorer, which supports rewardScore. This query parameter also appears in Fourier: Making Waves, so you can copy the information over and update the default value to 10.

[kathy-phet]

@arouinfar - Equality Explorer also supports ?gameLevels=1,2 , and maybe others - might need to ask @pixelzoom on that one.

[arouinfar]

Equality Explorer also supports ?gameLevels=1,2 , and maybe others - might need to ask @pixelzoom on that one.

Good catch @kathy-phet! Number Play and Fourier: Making Waves also support gameLevels and that's already been documented in the Teacher Tips. Many of the sims with games are too old to support gameLevels, and Equality Explorer was the only sim I found that was missing it.

@Nancy-Salpepi @KatieWoe for Equality Explorer, please include rewardScore and gameLevels. You can copy them from Fourier: Making Waves, but update the examples and defaults accordingly.

[pixelzoom]

@arouinfar - Equality Explorer also supports ?gameLevels=1,2 , and maybe others - might need to ask @pixelzoom on that one.

Confirmed -- the sims that support gameLevels are Equality Explorer, Fourier: Making Waves, and Number Play.

[Nancy-Salpepi]

@arouinfar on the Website, I noticed that Function Builder and Function Builder: Basics don't have pan and zoom listed (even though they have that functionality). Shall I go ahead and check that off under admin?

[arouinfar]

@arouinfar on the Website, I noticed that Function Builder and Function Builder: Basics don't have pan and zoom listed (even though they have that functionality). Shall I go ahead and check that off under admin?

Good catch @Nancy-Salpepi! Yes, please tag them.

[amanda-phet]

Sorry to jump in late here, but I think it would be good to add a checklist item to update the date in the footer of the teacher tips document.

[arouinfar]

Sorry to jump in late here, but I think it would be good to add a checklist item to update the date in the footer of the teacher tips document.

Thanks for the feedback @amanda-phet. Sounds like a good change going forward, so I'll add it to the checklist. However, I don't think it's worth addressing in the Teacher Tips that have already been uploaded to the website.

[Nancy-Salpepi]

@arouinfar all of the (English) Teacher Tips have been updated!

[arouinfar]

Awesome, thanks @Nancy-Salpepi @KatieWoe!

@DianaTavares @solaolateju -- QA has finished updating the query parameters section of all Teacher Tips docs. This included adding information about query parameters to Teacher Tips that did not previously include this information.

Closing.