smiths
commented
3 years ago I'll respond to each point in turn.
The Jupyter notebook in CaseStudies/projectileLesson.
- there is a clearly a need for meta-information. The first 4 paragraphs are about the document, but not the lesson itself. Apparently, there is some room for that - https://readthedocs.org/projects/nbformat/downloads/pdf/latest/ talks about metadata.
Yes, I agree that the "introduction" is not part of the pretend lesson. It is information for us to explain what we are doing and why. I also introduced a typographic convention for comments for us to read - like TODO items and thoughts. These comments are also metadata.
I agree that I'd rather not have this information in the lesson, but I also want it to be maintained with the lesson. The idea of putting this information in the json file sounds good, but the nbformat metadata doesn't appear to be what we are looking for. nbformat has an author field for metadata, we should definitely use that, but the other metadata doesn't seem to fit with our needs. I looked up how to add comments to json files and I was surprised to find that they aren't supported. I found a workaround that suggests adding data to capture the comments. (https://www.freecodecamp.org/news/json-comment-example-how-to-comment-in-json-files/) I'm not sure I like that idea since the comments become part of the data, but maybe that could work?
Another option is to create a separate document about the projectile lesson document. This might be the most practical way to proceed.
EDIT: I moved the meta information out of the jupyter lab to its own document in commit 22d4818.
- arguably, the first comment, about adaptation, should not be metadata. Attribution is an important part of research.
Agreed. I added a new introduction (in 7fef810) that doesn't include "meta data." The new introduction references the original source of the example (Hibbler).
- I wonder if the source material is consistent about using superscript c to mean constant? It's certainly the first time I see that notation, and I don't think I like it... But it's interesting.
My guess is that the text doesn't use the subscript c to consistently mean constant. There isn't a table of symbols in the document, or a typographic conventions section. I think each section of the text is self-contained. The quantities (like velocity, acceleration etc) use standard symbols, but the decorations (subscripts) seem to be inspired by the current section's needs.
In Drasil we can easily change the symbols. We could even enforce some semantic meaning and consistency to subscripts, although I don't think we do that right now. The textbook relies on a human for consistency. Not an easy task!
- I like how in the very first sentence, the words and their notation/name are defined very succinctly.
- too bad the equation numbers don't seem to show up. That makes the experience a lot less nice.
Agreed. I haven't yet tried Ting-Yu's idea of labels in the markdown. Hopefully that works. I don't like my solution of using Latex extensions; it feels too fragile.
EDIT: I've found a manual way to add tags that seems okay. The code for references is now done like this:
$$v = v^i + a^c t \label{Eq_rectVel}\tag{Eq_rectVel}$$
<a name="Eq_rectVel"></a>
From Equation [Eq_rectVel](#mjx-eqn-Eq_rectVel): $v_x = v_x^i$
- the notation v^i is not, however, defined! Same with p^i. Or time (t). (v^i)^2 is tremendously ugly.
Yes, the quantities v^i etc should be defined. I'll add them. (With Drasil it would be easy. Unfortunately I have to do it manually!) I also don't like the (v^i)^2 notation. I was following our Projectile example's notation for the initial velocity and when I had to square it, I need to do something to make it clear. Interestingly the textbook has the same problem, but a different solution. They use the symbol v_0 for initial velocity, so there isn't really much confusion with squaring it. However, when they want to introduce the x and y components, they use the notation (v_0)_x. Also ugly notation! There should be a better notation, but the use of subscripts in this way is fairly standard in engineering mechanics. We could use a different typeface, or a bar, or something to indicate initial, but that would be unusual. Maybe we could make it clear that v is a function of time, and talk about v(0) to mean the initial time?
EDIT: The symbols v^i and p^i are now defined in commit 0f6a53e.
The Jupyter notebook in CaseStudies/projectileLesson.