Can we add a list of features for this publication on Sim Checklist?
terracoda opened this issue · 19 comments
The sim checklist (https://github.com/phetsims/phet-info/blob/master/checklists/sim_checklist.md) focuses on the traditional design of a simulation.
When this checklist was renamed from "master checklist" to "sim checklist" we also discussed hooking the description design checklist which has some duplication see (https://github.com/phetsims/a11y-research/blob/master/issue-templates/description-design-template.md)
I'm wondering how best to make it clear what sim features are part of he sim checklist, and then when a feature is part of the sim checklist, a link to a related checklist when one exists can be added.
Here's what I suggest adding somewhere near the top of the Sim Checklist:
Inclusive Features
Checked features that are being worked on for next release of this sim
- Alternative Input
- Pan & Zoom
- Sound & Sonification (UI)
- Sound & Sonification (Pedagogical) - (include links to relevant sonification design document)
- Interactive Description - (link to description design & implementation checklist)
- Mobile A11y included
- Voicing - (include links to relevant voicing design document)
@terracoda - Can we have two checkboxes for Sound?
Sound: UI
Sound & Sonification: Pedagogical
UI sound is something that will be standard - to support alt input and pan zoom features.
Pedagogical sonification seems like it will be more often taken up when we have funding for description, since one of the multiple roles of sonification is supporting and coordinating with description.
Sure @kathy-phet, that sounds like a good idea.
@kathy-phet, do you have any thoughts on where feature list should go? Should it go right under the name and before the Design section starts?
@BLFiedler, should we add a second checkbox that specifically calls out any teaching materials specific to inclusive features, e.g., Sound Primer video, and ensuring Teacher Tips includes information about the inclusive features.
Assign me once you have solidified the content and I can add it.
EDIT: Or you can of course just add it yourself by editing https://github.com/phetsims/phet-info/blob/c37f555dfe2b4dd3c55f6e9401372574b4521dc8/checklists/sim_checklist.md directly
@markgammon - Can you look at this Sim Checklist and advise @terracoda here? Thanks!
@terracoda, happy to check in with some thoughts about adding content to the checklist. I'll ping you.
@BLFiedler, should we add a second checkbox that specifically calls out any teaching materials specific to inclusive features, e.g., Sound Primer video, and ensuring Teacher Tips includes information about the inclusive features.
Yeah, so I'm not sure how exactly to populate the list for this purpose, but it should somehow be indicated that whenever there's the addition of a feature with additional teacher resources, that they need to be created or updated.
Here's a link to the quad sim checklist I created for Teacher Resources, but I'm not sure what level of detail would be appropriate for the overall sim checklist.
At the time of writing, Sound and Sonification requires a Teacher Tips update and a Sound Features video. Interactive Description requires a Teacher Tips update.
@markgammon, I realize this is meant to be a high-level checklist. I feel like if we include upfront all features that are to be included when the checklist is opened, we can more efficiently use this checklist with other more detailed checklists, like the one I created for Interactive Description design and implementation (https://github.com/phetsims/a11y-research/blob/master/issue-templates/description-design-template.md). The goal for me is to remove any duplication from the description-design-template.md, so that checklist can just focus on the needs to design and implementation.
Things that might need to change/adjust:
- Where to include all features, e.g., should PhET-iO be added to the features section?
- What features (if not all) need to be explicitly called out?
I like that in the sim checklist calls out if the sim is a port or a new design. I could something like that to the description-design-template.md - something like design starting with a port, an HTML5 sim or starting from scratch?
Personally, I think it makes sense to have the list of features close to the top, so both the designers and developers know what features need to be considered throughout their processes.
@markgammon, I am not sure how to deal with this issue and updating the main checklist.
Is any action required of me for this issue?
Have a meeting with @arouinfar and @amanda-phet tomorrow to discuss and get some input on updating the checklist.
Things @arouinfar and @markgammon and I discussed:
- We wonder if something similar to the responsible dev file would be useful to build so that we have a ground truth for which features are in which sims. Or if there is an automatic way to see which features are in a sim, such as with phet marks. Might be worth a quick discussion with a developer about if this could be a way to achieve @terracoda 's goal of knowing which features a sim has? Going to a sim's checklist doesn't seem very efficient, as it would only apply to sims that are started after the modification to the main checklist. We can use the filter page on the website to get this information, but that also relies on someone remembering to check the box for the feature!
- Do we need pan & zoom mentioned? All future sims will have this going forward, so it might not need a checkbox.
- We like the idea of putting this section between Design and Implementation, and separating out the design and development work as separate checkboxes
- The PhET-iO list item is truly just "did we have a discussion about potential PhET-iO capabilities" and not really about full PhET-iO design or implementation. So I think keeping the checkbox where it is makes sense.
- To be consistent with how the sim checklist currently functions, these items should only be checked off when complete (likely at publication), and not just "if being worked on." When a sim is published, it should be clear which items were included, and which were not, based on if they are checked off or not.
Our recommendation for what to add to the main checklist (but of course, up for discussion):
Inclusive Features
- Alternative Input (Started: ) (Completed: )
- Pan & Zoom
- Sound & Sonification (UI)
- Sound & Sonification (Pedagogical) - (include link to relevant sonification design document)
- Sound design complete (Started: ) (Completed: )
- Development complete (Started: ) (Completed: )
- Interactive Description - (link to description design & implementation checklist)
- Description design complete (Started: ) (Completed: )
- Development complete (Started: ) (Completed: )
- Mobile A11y included
- Voicing - (include links to relevant voicing design document)
I think checking off the features as they are completed makes sense.
I wonder then, if removing the feature if it is not expected to be included in the next major release is a good idea. I am assuming that a new check list would be needed if work on a new and extensive feature started after initial features were implemented and published.
Actually, that thought makes me wonder how this checklist is used across the team. Is it for first design and implementation of a simulation or is it used each time a feature is added to a sim and follows a new publication timeline?
I do generally note at the top of my Interactive Description Design Doc what features are being worked as I start my own description designs, but that's not the right place.
Perhaps a shared responsible designer file is needed that just defines features as they progress? Does the responsible dev file already track this information?
And I am open to using the suggested checkboxes above, perhaps a simple note next to the feature can indicate whether it is included or not, for example:
- Interactive Description - (not this design cycle)
- Voicing - (not this design cycle)
OR
- Interactive Description - (not this publication cycle)
- Voicing - (not this publication cycle)
It sounds like adding the suggested checkboxes in Amanda's comment in between the Design and Implementation sections and noting whether the feature is included, along with (Started: ) (Completed: ) is a good step. And a follow up would be to consider a shared file, like the responsible dev, to better track the features for each sim (the responsible dev file does not track this now). @amanda-phet and @arouinfar does that work for you? @terracoda do you need help with updating the checklist?
Sounds good to me @markgammon!
That sounds good to me.
The responsible dev file has a responsible dev and responsible designer. For most sims, there is a "lead", whether the design includes visual, audio, description... the last person to lead the sim is the lead. So I think we might want to think about what new column(s) that file needs. In many cases, the lead designer is the lead pedagogical and visual designer. When that's not the case, maybe we can just add an additional designer (and even specify their lead role?).
For the purposes of this issue, I can modify the main sim checklist and close this issue. I will open a new issue for discussion about the responsible dev file.
Thanks @amanda-phet.