search

phetsims / ratio-and-proportion

"Ratio and Proportion" is an educational simulation in HTML5, by PhET Interactive Simulations.
GNU General Public License v3.0
1 stars 4 forks source link

model.md doesn't seem targeted to teachers #307

Open jbphet opened 3 years ago

jbphet commented 3 years ago

From code review issue #286, specifically the item that says, "Does model.md adequately describe the model, in terms appropriate for teachers?"

In my opinion, this description as currently written seems targeted at developers rather than teachers. It describes specific source code files, ratio values that are never presented to users, and some sim-specific terminology that a user would not encounter. This is valuable information, but it should probably be moved into the implementation-notes.md file and the model.md be rewritten with something more general about what the sim does and why. I just looked at the model.md for the "Natural Selection" sim, and though it's way longer than would be needed for "Ratio and Proportion", I think it captures the idea of explaining the important ideas about what is shown in the sim without getting into how the sim does it. See https://github.com/phetsims/natural-selection/blob/master/doc/model.md.

zepumph commented 3 years ago

Ahh, that distinction makes a lot more sense. Thanks. I will work on this.

emily-phet commented 3 years ago

I had no idea there were model notes targeted at teachers. I don't know that we actually tell anyone outside of PhET that this exists. The natural selection example is great! Drafting this during the development process and having this be seen and discussed by the design team might be a great way to help designers better understand the current model as we go...what doesn't make sense in the drafted doc could be discussed for clarification, and the doc could be used for reference by designers without a related science background.

zepumph commented 3 years ago

I also didn't realize the target audience of model.md.

Having this around during the design process is a very good idea! It sounds like the best people to review my changes for this issue would be designers. I'll ping you about it.

zepumph commented 3 years ago

A large point here will be to discuss how the fitness is calculated based on "physical distance" or "hand positions" or "hand proximity" to the ratio. No on the mathematical closeness/distance between the current ratio and the target ratio. This handles edge cases like when the current ratio is at 0/0. Like in https://github.com/phetsims/ratio-and-proportion/issues/288

zepumph commented 3 years ago

@emily-phet, will you please give this a onceover and feel free to change anything you would like. https://github.com/phetsims/ratio-and-proportion/blob/master/doc/model.md#. Also feel free to close.

emily-phet commented 3 years ago

@zepumph This looks very close. I'd like Brett to work with you to make this one notch more specific, with an eye towards using plain language everywhere possible.

@zepumph can you share @BLFiedler a link to a few other examples, perhaps one from Chris and one from JB, and show @BLFiedler how to edit this markdown file (if he doesn't know).

@BLFiedler Can you take a look at the examples, and make some edits to the RaP version. Definitely discuss with @zepumph as needed for accuracy. Imagine a general teacher reviewing this, as well as someone like Clayton or a colleague of Dor's taking a look (e.g., someone who is not already familiar with Dor's proportion work, but savvy and will get the gist).

Let me know if you have any questions. I'm guessing Brett will be able to identify some areas where a little more detail or a little friendlier language would be helpful, if that's not the case I can hop on a call and be more specific about where I think some improvements could be made.

Now that I know this general audience model description exists, we should definitely cite in upcoming papers, so we'll want it to be in good shape for that!

zepumph commented 3 years ago

JO: https://github.com/phetsims/proportion-playground/blob/0cf288e3a8353f3a23183763bd904241d6e701da/doc/model.md

CM: https://github.com/phetsims/equality-explorer/blob/0cf288e3a8353f3a23183763bd904241d6e701da/doc/model.md https://github.com/phetsims/function-builder/blob/2ab967f77688c0d7ec828589445771606640ed54/doc/model.md

JB: https://github.com/phetsims/number-line-operations/blob/da845fd6ca13f556ef2d947c09197edcce5cef66/doc/model.md

Feel free to edit through github with https://github.com/phetsims/ratio-and-proportion/edit/master/doc/model.md. If you make a commit, please paste a link to this issue (https://github.com/phetsims/ratio-and-proportion/issues/307) into the commit message. See https://guides.github.com/features/mastering-markdown/ for a guide to github flavored MD if needed.

brettfiedler commented 3 years ago

Alright - gave it a shot! @zepumph, can you look over for accuracy? And I'll tag @emily-phet if she'd like to glance it over, but not assigning.

zepumph commented 3 years ago

Looks really good. Thanks. A couple edits above. Feel free to edit as you wish and reverse any of them. Please close when you are done with the markdown.

brettfiedler commented 3 years ago

Looks good to me. I suppose I should remember in the future to shrink my window (widescreen monitor) when checking how the layout looks :)

emily-phet commented 3 years ago

Re-opening, assigning to me. I'd like to make some tweaks.

terracoda commented 2 years ago

@emily-phet, have you made your tweaks?

terracoda commented 2 years ago

Just asking as we head towards re-publication.

zepumph commented 2 years ago

This does not block our release. @emily-phet will get to it as time permits.