What's Wrong with these Equations? (1989) [pdf] | Hacker News Reader

What's Wrong with these Equations? (1989) [pdf]

pamitc.org

35 pointssieste8 comments

Good rule. If I may add a derivative rule about coding articles and tutorials.

Please please put filenames to each and every code snippet.

Example working with any modern js-stack there are a gazillion (ok not really) files to keep track of: package.json,main js, index.js, app.js etc etc.

Another example: Any language that uses some sort of modules.

Knowing what the filename is of code-module-snippet makes it much easier for an outsider or newcomer to understand the context and actual article.

ok rant over :)

Yeah my brain immediately went to how/if this should be applied to code listings, too. A while back I wrote an article[1] that used somewhat lengthy chunks of C code, which I felt could not be abbreviated. I ended up highlighting the lines which I discussed later in bold, a different color, and with a reference number in brackets, to which the prose referred. I could maybe have done line numbers, which I think is the closest match to what this article proposes, but it's a bit tricky because I wanted to refer to multiple lines when discussing some subjects. I'm satisfied with how I did it, but I still wonder if there's a better option.

[1] https://www.smokingonabike.com/2021/02/28/hacking-super-monk...

Dave Mermin is one of my famous profs, one of very few who will stop to look around and see what is really going on when everybody else is too busy publishing and perishing.

As a former technical writer, I suggest that the "math is prose" rule is valid only under the assumption of mathematically minded readers. To normal people, an equation or other mathematical expression might as well be one of those black blocks in a redacted government document. How are they supposed to know that a set membership symbol or a logical implication arrow should be read as a verb? It's not much extra effort to treat expressions as nouns by writing "we conclude that p -> q holds whenever x and y are the same" instead of "we conclude p -> q iff x = y", and doing so may make the difference for some readers between missing a few details and feeling completely excluded.

I disagree with the number-every-equation rule (Rule 1). It sounds like the math equivalent to adding extra complexity to code so it will be "ready" for extension in the future.

I prefer to number only the important equations that the reader really needs to know and focus on, and remember. Thus appearance of the equation number signals to the reader "this is important." If I were to number every equation, I'd be losing this communication signal.

In fact I find mainstream textbooks (for undergraduates) to be really overwhelming with the visual elements (colors, boxes, extra emphasis). If you flip through a physics or a calculus textbook you'll see all kinds of boxes that call for your attention: THIS IS IMPORTANT, THAT IS IMPORTANT TOO, etc. one on every page, but in the end when everything is important, nothing is.

In fact every chapter has one or two main equations that you really need to know. Put those in a box, and number them if you want, but leave all the other "anecdotes," derivations, and special cases unaccented please.

I also prefer to number just the important equations. One of the advantages of numbering all equations is that the reader can binary search an equation by number. I try to mitigate that loss by providing page numbers or section numbers.

Providing “contrast” is something I appreciate as a reader. It is much easier to provide in person, on a whiteboard. Maybe we need papers to have references to YouTube derivations :)

Found a couple of links to the complete scanned copies of this article:

- http://www.pamitc.org/documents/mermin.pdf (colour but slightly cropped)

- http://www.ai.mit.edu/courses/6.899/papers/mermin.pdf (black and white full pages)

Changed to the first one from https://physicstoday.scitation.org/doi/10.1063/1.2811173. Thanks!

Reply on news.ycombinator.com