model.md doesn't seem targeted to teachers

[jbphet]

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]

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

[emily-phet]

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]

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]

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 #288

[zepumph]

@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]

@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]

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]

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]

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]

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]

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

[terracoda]

@emily-phet, have you made your tweaks?

[terracoda]

Just asking as we head towards re-publication.

[zepumph]

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