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.)
> The sentence “Let x⋆ be the solution to the optimization problem” implicitly asserts that the solution is unique. If the solution is not unique or need
not be unique, write, “Let x⋆ be a solution to the optimization problem.”
I know this point is meant to be about precision in writing but this reminded me of Perron's Paradox, which highlights the danger of assuming the existence of a solution without proper justification. The problem can be demonstrated through the following argument:
Let n be the largest positive integer. Then either n = 1 or n > 1. If n > 1, then n^2 > n contradicting the definition of n. Hence n = 1.
This fallacy arises from the mistaken assumption that a largest integer exists in the first place.
The original post is a great submission, by the way. Thank you for sharing it on HN. Bookmarked already!
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.
Well, particularly in a subthread on Strunk & White, one should write "...differ on only two points" or "...contest only two points."
It's not that we ONLY contest these points (we may also, e.g., state them or rephrase them). It's that we contest ONLY these two (and no others). See the antepenultimate example of Rule II.16, "Keep related words together."
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.
Also bear in mind that Strunk and White's Elements of Style is tailored for American English. Should you be writing for a British publication, the differences are numerous. Not quite as numerous as the commas and quotation marks that you shall omit, but still worth having within your ken.
"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.
Although this is about LaTeX (not AMS-LaTeX) and is from 2014 (and I don't remember when this AMS-LaTeXism was introduced), nowadays instead of having to decide when to use `\ldots` and when to use `\cdots` one can use things like `\dotsb` for dots between binary operators and `\dotsc` for dots between commas. There are others that I don't remember, because those fulfill most of my needs. There's even `\dots`, which tries to determine what kind of dots are appropriate from context (and usually does a good job!).
From the abstract "The guidelines here cover both the LaTeX source as well as the output, so this PDF is intended to be read alongside its own source code," which I found here:
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.
Seems that what is needed is something more automated, beyond a "simple" linter like ChkTeX and more towards what Word has in its readability scores, combined with the local rules of Stanford's house style. State of the art here seems still in its infancy.
Readit News
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.)
I know this point is meant to be about precision in writing but this reminded me of Perron's Paradox, which highlights the danger of assuming the existence of a solution without proper justification. The problem can be demonstrated through the following argument:
Let n be the largest positive integer. Then either n = 1 or n > 1. If n > 1, then n^2 > n contradicting the definition of n. Hence n = 1.
This fallacy arises from the mistaken assumption that a largest integer exists in the first place.
The original post is a great submission, by the way. Thank you for sharing it on HN. Bookmarked already!
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
https://www.mit.edu/~dimitrib/Ten_Rules.pdf
I submitted a link here earlier in the same spirit that you might appreciate:
https://hn.algolia.com/?query=%22https://mathcomm.org/writin...
It's not that we ONLY contest these points (we may also, e.g., state them or rephrase them). It's that we contest ONLY these two (and no others). See the antepenultimate example of Rule II.16, "Keep related words together."
“…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.
https://github.com/michaelchanwahyan/latex_templates/blob/ma...
Why would it have been? It seems intended to be navigated by visitors.
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.
Example: https://www.cs.umd.edu/~nspring/software/style-check-readme....
For example, seeing a lot of double-backslashes (\\) in a LaTeX source file would be a code smell to me if not actually illegal LaTeX.