jaltekruse / free-math Goto Github PK

Topics to cover:
Tips on using the editor, superscripts/subscripts, typing symbols, fractions.
Introduce clone problem, describe use cases.
Talk about how to manage files, warn about broken auto-save on district chromebooks.

While MathQuill is unlikely to produce something that Katex cannot render, it would be good to confirm that the MathJax based fallback for the static TeX component is functioning properly as I had noticed missing assets in the web debugger in the past.

Mathematicians are not the primary audience currently be targeted for Free Math, but some advanced users may like to use the editor to produce work that will eventually be included in a larger Latex document. Users can currently extract the Latex from the simple JSON format of the saved work, but this assumes a cross section of knowledge between LAtex/Math and some basic programming or file formats knowledge.

A basic exporter that would produce a reasonable Latex document version of a Free Math assignment file would be useful to these kinds of audiences.

https://www.sitepoint.com/html5-local-storage-revisited/

I am currently working around this by no re-rendering the expressions. This caused problem when I tried to implement deleting and adding individual steps anywhere in the list. In this case I cannot use the index in the list as the React DOM element key.

Currently when viewing a list of similar assignments, if a teacher decides to grade a problem group they will have the standard buttons for applying a score across a group shown to them.

The problems shown can and likely will be a subset of the overall solutions in that group (the students who got a similar answer and this problem, but the rest of their assignments were unique enough to leave them out of this group of overall similar assignments). Currently the bulk actions apply to all answers on the problem that were similar, not just those shown in the filtered list.

Teachers should always have intuitive access to the full student work to check that the work shown justifies the answer provided.

That being said, teachers may not want to re-grade answers when looking at the rest of the class.

Fixing this will require thought about expected workflow. If teachers would complete all regular grading, and then look at the similar assignments this would be less of a problem.

I could consider disabling the bulk actions, or all grading when looking at similar assignments. If the determination made on this screen will be discarding the whole assignment for improperly sharing work. I think some users will expect to be able to downgrade specific problems.

Both for teachers and students, also need to add more thorough upgrade tests, including the format for grading feedback.

Add an "x" button next to a step to allow deletion. Having a popup to prevent accidental deletions could be annoying, the alternative could be to add a more comprehensive undo-redo. The current one can only add/subtract from the end of the list.

The events most of the time don't work unless you leave the graph, come back and carefully move until you can see one of the hover boxes while over one of the bars, then you can click and it works.

If I can't fix chart,js, looking quickly at their issues it appears to be an issue that has been around for a while, I can just add a workaround with buttons to move between problems that will sit below the graph.

For assignments that deal with very specific formatting, such as those requiring proper significant digits, or final answers in standard form, the current approximate expression matching used to create the groups would not be very helpful.

A basic solution could simply be a toggle that would allow an assignment, specific problem, or specific answer group to be re-arranged using a more exact match. Even in this case, it probably should not be a string match on the Latex, as the editor is now configured to allow spaces. Some other differences, such as extraneous parenthesis could possibly be ignored as well, but this would be harder to determine, as it would require analyzing the expression tree with and without the parenthesis.

Overall this will be a processes requiring improvement over time, but covering some basic cases at first would be a good start.

This data is used to uniquely identify docs (especially untitled documents). Including milliseconds solved a timing/uniqueness issue in the past with very fast edits. This data should be left out of the display to remove clutter.

Several users have tried opening a free math file by double clicking on it, which opened it in notepad on windows, which caused them to report it was "showing an error", as it just shows them raw JSON.

In the short term, if the file stays a simple text/json for any significant time, a message can be included in the files, somehow pegged to the top of the JSON directing users to the site. This might require custom JSON serialization as different browsers could have different key orderings in objects.

Longer term solutions might look something like creating a chrome app or similar to get more access to the underlying OS and possibly hook into the default apps list.

Coming from a background of compiled languages, I like to avoid some pitfalls of javscript. One poor workaround I used in Free Math was to access all members of objects/maps using string constants so I could avoid mistyping property names and only noticing during runtime. This strategy does work to solve some of my problems with javascript, but it makes the code ugly and non-standard. Also now that I have broken it into reasonable sized individual files, I have the string constants re-declared all over the place. Unfortunately this strategy will cause the need for upgrade code to be written for the old files once proper camel case property names are used, but this will just be a one time headache.

Either of these typing systems would also give general type safety and allow nice enums to be used where strings currently appear throughout the data structures and Redux action objects.

Would make the list easier to look through for students in earlier math classes.
Probably useful to include an "all" tab that shows the current view as well for advanced users.

MathQuill issue: mathquill/mathquill#790
Examples:
\not\subset -> turned into two separate symbols
\R, \N (sets of numbers) -> produces this, which is proper latex but cannot be parsed by MathQuill. \mathbb{R}

Probably easiest to hide this in a popup menu.

There are no restrictions on what students can submit. This is nice as it avoids the need to set up a problem list or answer key, but it can cause issues while grading.

This should probably be implemented as a warning, if only a small fraction of students submitted a problem. Teachers may want to not give any credit, but if a student just accidentally submitted the wrong problem, they may be fine giving them credit for it in place of a problem that was in the assignment. Possibly with a comment to more carefully read the assignment in the future.

Currently the grade calculation does not consider any kind of "correct problem list". So unfortunately if teachers don't notice the anomaly in the graph at the top of the page, a student may accidentally get extra credit for submitting an extra problem.

Not quite sure how hard this would be to add to the editor. It has support for curly braces {} for use as grouping symbols. It might be hard to make it intuitive with just a keyboard as the giant curly brace for linear systems should probably be totally distinct from the grouping symbol.

Users would need a way to enter a variable number of expressions, which is a similar problem to managing the size of a matrix.

Possible solutions could include an extra step during insertion, similar to the table insertion in modern MS Word. There they show a mini grid and users highlight an N by M rectangle to pick the size.

Another possible solution is starting with some minimum number in each direction and giving a button on the interface to insert a new row/column. This might have complexities of expectations to behave like an excel table, with the options to insert rows and columns above and below (or to the left/right) of any existing ones.

The assumption with the graph summary is that problems sorted to the right should likely be problems where all students got the right answer. This should often be the case, but it can also represent cases where there are common misunderstandings caused many students get the same wrong answer. A way to quickly verify this answer against an answer key, without having to click on each problem would help identify these cases. A mouseover on the graph could include the final answer reached by the largest number of students.

If a teacher goes through to give specific grades to a number of different students in a group, the "apply to all" button becomes destructive. The button is useful if a teacher accidentally applies a score incorrectly to everyone, but the destructive nature of the button should be conveyed if it is hit accidentally.

To avoid annoyance when teachers want to use to to apply to everyone, possibly not yet understanding what "apply to ungraded" means, the problems can be checked for grades, and only if several unique grades appear a warning can be shown.

The auto-save list can currently become cluttered very easily. The serverless architecture of the app makes me less confident about instantly deleting the auto-saved entries, as users could lose track of their files. New users especially could fail to realize that the files end up in their download folders and feel that they have been lost.

This could instead by handled by adding a state to the auto-save of "recently saved", with some information about when it was saved to disk. These entires could possibly be hidden by default to keep the list cleaner. Indirection can cause confusion, they could also possibly appear grayed out instead.

Currently Free Math runs the Babel transpiler in the browser, this makes loading on mobile very slow and is not recommended for production use.

If this is possible in a unit test that would be good, not sure if Node has access to these browser APIs.

I'd like for students to be able to submit a graph or a drawing with their work.

After opening an assignment or the grading experience, hitting the back button will take uses away from the site, rather than back to the homepage.

Not quite sure how fluid the experience can be made in the case where several assignments are opened in succession. The auto-saved data could provide the last state of each assignment in most cases, with a message about the assignment missing from the auto-save list if it failed due to insufficient storage. This is not fully reliable because there is no server that holds onto the data that can always retrieve and document for a URL.

This is used so commonly in written math that it feels necessary for students to clearly represent what they are changing between steps whenever two terms cancel out in an expression.

Thinking this should work like the parenthesis, after highlighting part of an expression, pressing a key (possibly backslash?) should "enclose" this expression with a wrapper that will put a line through the expression.

This won't be entirely intuitive (neither is the parenthesis behavior) because typing when something is selected in a text editor normally replaces the selected text. Should also consider ways to introduce these editor behaviors to users.

Add tests that use the Nightwatch wrapper for Selinium, or the new headless chrome to test the app end to end.

And give clear message to user if opening a giant file or grading session fills up the storage suddenly.

Students will likely learn not to check "complete" problems that don't get a grade for feedback as they generally won't have reason to believe teachers looked at them.

There is nothing stopping teachers from giving feedback without docking any points, and likely should continue to be allowed. Lots of teachers are talking about the negative impacts of grades punishing kids and not providing feedback in a way that makes them want to re-engage with the material.
https://www.kqed.org/mindshift/52456/a-grading-strategy-that-puts-the-focus-on-learning-from-mistakes

https://www.facebook.com/groups/teachersthrowingoutgrades/

Often times students will reach similar answers because they made similar mistakes, the ability to apply feedback text across a group could be helpful in these cases.

Unfortunately even similar work can involve different numbers of steps, so applying grading highlights to other students' work could be much more involved. This will likely be a follow up issue, but it can be considered when solving this problem for possible interactions between the two features.

Button to go back to top is still useful, but the message should probably be customized to avoid confusion.

See issue #17 and #18 for some complexities around this

Commonly used LMS systems to cover:

Google Classroom
Moodle
Canvas
Blackboard
Desire 2 Learn

This might be as simple as links to the docs for these different systems. While these have been deployed in many school districts and universities for a number of years, math teachers often aren't very familiar with collecting files from students as there aren't many useful file formats for representing math work.

There are a few outstanding patches, none have been merged in. I'd rather not maintain a fork of the editor.

mathquill/mathquill#332
mathquill/mathquill#315

A previous bug with MathQuill caused some keyboard inputs to produce latex that could not be parsed. While fixing these problems at the source is ideal, this particular problem allowed an exception to get all the way to the browser and brick the app. Just clearing a step in these cases and showing the rest of the data, either in the assignment editor or grading pages would allow work up to that point to still be saved.

Repro - clone problem in middle of doc

Problem - the last problem in the doc ends up with the cursor, so doc also scrolls confusingly.

Could just fix the text feature in mathquill - mathquill/mathquill#794

Advantage: can mix text and math
Disadvantage: makes the math editor more complicated, could make comparing things harder if students end up with variables in these text elements instead of just typing letters while in "math mode"

Could have a discrete concept in the app of a step that is text, and could switch between the two explicit modes. The text mode with just show a basic HTML textbox, so no opportunity for mixing math and text. Slightly more complicated UI at add the switch mode button, but makes the feature more discoverable than how mathquill allows typing text.

KAS is used for the similar answer check. Currently two expressions being determined to be equal and of the same form are put in the same group. To add more student work to the group the new candidate only has to match the first expression in the list.

This could lead to cases where A, B and C all end up in the group, but A compared directly to B may not report equality. I need to understand what kinds of semantic comparisons are being used to determine if there are risks here of inconsistent behavior based on ordering of student files.

matches = ( KAS.compare(groupAnswer, parsedStudentAnswer).equal && groupAnswer.sameForm(parsedStudentAnswer));

To see the problem, add like 15-steps in a problem, as you are editing the next step the undo/redo and other buttons will not be visible on the screen and you have to scroll back up to see them.

Would be better to have complete pages with a specific workflow and clear text/screenshots. The pages are generally pretty straightforward, but several include more info that teachers need, and it would be good to remind them at the end of each how they get the grades into their gradebook, instead of making them match up the general directions in Free Math "getting started" with the external pages' directions for dealing with zip files and such.

Free Math is currently designed to be stand alone, with communication between teachers and students represented in files. While this provides flexibility for use with many systems, it does involve some manual work to organize everything.

Processes that could be optimized include avoiding the need for students to manage their files and upload them into the LMS. If these could be saved directly into whatever system a school is using it could remove some busywork and provide an auto-save that would be accessible anywhere, rather than just stored within the browser on a single device.

Direct integrations could also allow automatically updating grade books, as teachers currently need to copy the grades out of Free Math into their grade book.

I assume LMS systems allow teachers to upload files to update their gradebooks. It would also give teachers a format they know how to work with in excel if they manage their grades more manually.

The summary graph currently only shows data about what was submitted by students. The graph tries to be ordered by which problems were often missed by students. The app has limited knowledge about what the problems actually involve. Teachers can use their knowledge of the subject and assignment to decide on the right problems to grade, with the assistance of the graph.

Teachers that don't process the problems in order (either numerical order or the one given in the graph) could lose track of which problems are graded an which are not. Some indication of how many of the solutions for a given problem have been graded would be useful.

Until recently re-opening partly graded documents could cause different groups of similar overall assignments to be calculated, as grading adds data into the tree with the student work.

This was fixed, but automated tests should be added to ensure this doesn't regress. This was implemented by cleaning out the grading info before comparing them. New grading data that gets added will require updates to this cleaning code, and tests would serve as a reminder to do so.

It appears there is some kind of timing bug in the code that should de-select a MathQuill editor when another gains focus. I have seen this a few times before, but have not been able to consistently reproduce it.

Some may have a csv format we could generate to reduce manual busywork copying over grades.

Complete integration removing file management would be nice too, but this would be a nice incremental step at improving experience, it's the one part of the teacher workflow that doesn't happen in bulk right now.

Pre algebra
Algebra (factoring, solving and simplifying expressions/equations)
Statistics
Physics
Chemistry
Calculus
Differential equations

See here: https://productforums.google.com/forum/#!msg/google-education/TiXVJW9ao9g/QOGwp-wpAwAJ

No response on this issue, may need to work around this by storing as a cookie?
Would work okay for student docs, but the size limitations would make it a poor option for the grading info for a whole class.

Might need to just wrap the site into a chrome app to make this work. Which is just annoying because the chrome store is disabled on all chrome browsers except those on chromebooks. https://developer.chrome.com/apps/migration