Good guide, but IMO it is missing one crucial recommendation: Use prose only to provide motivation, connect ideas, and guide the first-time reader. Any definitions, lemmas, theorems, corollaries, and proofs belong in typographically clearly separated sections and, most importantly, they should be fully self-contained and mention all assumptions! There should be no implicit context, no implicit assumptions from 5 pages before, no "drive-by" definitions and proofs in the prose.
Math papers written like contiguous novels are absolute hell to read & understand & use as reference. (Is the author assuming the same properties here as in the other argument on the previous page? What is that symbol again? Am I looking at an example here or is this already the proof of the the general theorem from the previous page? Etc.)
"Write to allow skipping over formulas" is great advice beyond just mathematics. Many a technical blog contains something like "I opened the file and look what I found!" followed by line after line of someone else's code or, even worse, a log file. Paraphrase your displayed matter so I can read your text fluidly. If I want to dig deeper, I'll go back and parse the details carefully.
I only contend on two things. First is recommending Strunk and White - in general a style guide should not stifle writers' voices and instead equip them with tools to express their own. Here I would rather recommend the far more authoritative and comprehensive The Chicago Manual of Style [1]. Second is excess punctuation - easily incurs in too much line noise. You should generally avoid adding distracting elements seldom added pro forma.
The best source for me has been the Handbook of Writing for the Mathematical Sciences by Nicholas J. Higham [1]. His I can fully get behind. Another is Writing Mathematics Well by Leonard Gillman [3]. Still another is Mathematical Writing by Franco Vivaldi [4].
With regard to your comment, and since we are on the subject of style, I would rephrase "... only contend on two things" as "... only differ on two things". While it is grammatically correct, it feels awkward.
Why does “I contend” feel awkward to you? It is more specific than “I differ” because that could also mean that the author physically differs, which is awkward, while “contend” is specifically used for disagreement on some topic? Does “I contend”
maybe has a ring to it of being scholastic/pretentious? (Also non-native English, just curious)
I think the trouble in the phrase is that “contend” has an active sense to it whereas “on” creates a more passive tone. Your solution is to swap to a more passive phrasing, but the alternative is also available.
My personal pet peeve is point 3 under "Use the right commands"
There are quite a few math textbooks that don't use \left and \right, even with tall notation like integral signs. The resulting expressions are much harder to parse visually.
Good guide, but IMO it is missing one crucial recommendation: Use prose only to provide motivation, connect ideas, and guide the first-time reader. Any definitions, lemmas, theorems, corollaries, and proofs belong in typographically clearly separated sections and, most importantly, they should be fully self-contained and mention all assumptions! There should be no implicit context, no implicit assumptions from 5 pages before, no "drive-by" definitions and proofs in the prose.
Math papers written like contiguous novels are absolute hell to read & understand & use as reference. (Is the author assuming the same properties here as in the other argument on the previous page? What is that symbol again? Am I looking at an example here or is this already the proof of the the general theorem from the previous page? Etc.)
"Write to allow skipping over formulas" is great advice beyond just mathematics. Many a technical blog contains something like "I opened the file and look what I found!" followed by line after line of someone else's code or, even worse, a log file. Paraphrase your displayed matter so I can read your text fluidly. If I want to dig deeper, I'll go back and parse the details carefully.
This is great advice.
I only contend on two things. First is recommending Strunk and White - in general a style guide should not stifle writers' voices and instead equip them with tools to express their own. Here I would rather recommend the far more authoritative and comprehensive The Chicago Manual of Style [1]. Second is excess punctuation - easily incurs in too much line noise. You should generally avoid adding distracting elements seldom added pro forma.
The best source for me has been the Handbook of Writing for the Mathematical Sciences by Nicholas J. Higham [1]. His I can fully get behind. Another is Writing Mathematics Well by Leonard Gillman [3]. Still another is Mathematical Writing by Franco Vivaldi [4].
[1] https://www.chicagomanualofstyle.org/home.html
[2] https://epubs.siam.org/doi/book/10.1137/1.9781611976106
[3] https://bookstore.ams.org/mmbk-7/
[4] https://link.springer.com/book/10.1007/978-1-4471-6527-9
With regard to your comment, and since we are on the subject of style, I would rephrase "... only contend on two things" as "... only differ on two things". While it is grammatically correct, it feels awkward.
Why does “I contend” feel awkward to you? It is more specific than “I differ” because that could also mean that the author physically differs, which is awkward, while “contend” is specifically used for disagreement on some topic? Does “I contend” maybe has a ring to it of being scholastic/pretentious? (Also non-native English, just curious)
You're right, thanks. English is not my mother tongue so I still fall for some language traps.
I would comment to drop the preposition:
“…only contend two things”
I think the trouble in the phrase is that “contend” has an active sense to it whereas “on” creates a more passive tone. Your solution is to swap to a more passive phrasing, but the alternative is also available.
May I add a more concise yet helpful presentation of Prof. Bertsekas Ten Simple Rules for Mathematical Writing
https://www.mit.edu/~dimitrib/Ten_Rules.pdf
Does anyone have suggestions for math textbooks that follow these writing rules?
Nice! I haven't seen this one yet.
I submitted a link here earlier in the same spirit that you might appreciate:
https://hn.algolia.com/?query=%22https://mathcomm.org/writin...
My personal pet peeve is point 3 under "Use the right commands"
There are quite a few math textbooks that don't use \left and \right, even with tall notation like integral signs. The resulting expressions are much harder to parse visually.
I'm surprised at how applicable this is to writing in general. Very good guide.