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.
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:
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.
I am less delighted, than some in the comments. I mean, most of the advice is genuinely good general writing advice, so general in fact, that it borders on advices like "be good". Typography advices are good. But if we keep in mind that this is not really a recommendation, but pretty much an obligatory guide to follow for the intended audience, the more specific writing advice doesn't amuse me. Why cannot I start a sentence with a symbol, and must insert filler-words, why do ∀ and ∃ only belong to formal logic? The author of the guide may prefer it like that, but why enforce it?
But that's not why I wanted to comment. The whole document makes me think, that the whole generic structure of how one writes papers, should it still be done like that? Does enforcing it do more good than harm? Can it be changed?
I do not belong to academia, so where I'm coming from is having to read this stuff when researching anything. And the general sentiment I want to express here is that I really don't like to have to read these things. To be fair, it is less applicable to math papers, than other topics, but academic papers are not easy to get information from, the main thing they are supposedly exist for. You can sometimes find a blogpost which essentially contains the same information, but is much shorter, clearer and niced than the accompanied paper. And it just comes down to format. I mean, it probably does play on paper reasonably well, when you have it printed out and intend to read it fully, repeatedly, using a highliner. But it is not how most of the people read them most of the time, right? Most of the people read it on a screen, first when trying to understand how is it related to what they are researching now, then as a reference. And pretty much everything about these papers is awful for that.
First off, abstracts. Absolutely essential thing in theory, woefully misused most of the time. I don't want an abstract, I want a TL;DR. I don't want to read empty words about what it "explores" and such, I want to read as full and as condensed final result, as possible. If there is a concrete finding, I want it as the first sentence.
References. I don't want neither [BV04] nor blah-blah Somebody et al [BV04]. I want clickable links to resources whenever possible. They don't have to be academic papers, it can be anything that helps me to learn more about the topic in the shortest amount of time.
Code. Code is close to useless on paper, I want it to be on GitHub, with a clickable link. All excerpts that you have in your paper, I want them to be highlighted, because that's how it's supposed to be read, there is a reason why everybody but 90 years old professors use highlighting.
Instead of ugly hard to read plots in these papers there are dozens of JS libraries to make interactive plots that can help you show anything you want to show.
Even the mere fact I have to read a PDF off my screen, which I cannot resize to my liking, is annoying. Why must it be paper-first in 2024, when everything is screen-first? Surely there can be rules in these guidelines to make these documents easy to print as well, given how much time one is supposed to spend on correct typographics in LaTeX.
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.
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:
https://github.com/michaelchanwahyan/latex_templates/blob/ma...
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
I vote for 'and'. Strunk & White and the CMS serve different purposes; the latter is more of a reference work but both are valuable.
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
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...
Does anyone have suggestions for math textbooks that follow these writing rules?
Bertsekas' textbooks of course, which I think are very well-written and a pleasure to read.
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.
I am less delighted, than some in the comments. I mean, most of the advice is genuinely good general writing advice, so general in fact, that it borders on advices like "be good". Typography advices are good. But if we keep in mind that this is not really a recommendation, but pretty much an obligatory guide to follow for the intended audience, the more specific writing advice doesn't amuse me. Why cannot I start a sentence with a symbol, and must insert filler-words, why do ∀ and ∃ only belong to formal logic? The author of the guide may prefer it like that, but why enforce it?
But that's not why I wanted to comment. The whole document makes me think, that the whole generic structure of how one writes papers, should it still be done like that? Does enforcing it do more good than harm? Can it be changed?
I do not belong to academia, so where I'm coming from is having to read this stuff when researching anything. And the general sentiment I want to express here is that I really don't like to have to read these things. To be fair, it is less applicable to math papers, than other topics, but academic papers are not easy to get information from, the main thing they are supposedly exist for. You can sometimes find a blogpost which essentially contains the same information, but is much shorter, clearer and niced than the accompanied paper. And it just comes down to format. I mean, it probably does play on paper reasonably well, when you have it printed out and intend to read it fully, repeatedly, using a highliner. But it is not how most of the people read them most of the time, right? Most of the people read it on a screen, first when trying to understand how is it related to what they are researching now, then as a reference. And pretty much everything about these papers is awful for that.
First off, abstracts. Absolutely essential thing in theory, woefully misused most of the time. I don't want an abstract, I want a TL;DR. I don't want to read empty words about what it "explores" and such, I want to read as full and as condensed final result, as possible. If there is a concrete finding, I want it as the first sentence.
References. I don't want neither [BV04] nor blah-blah Somebody et al [BV04]. I want clickable links to resources whenever possible. They don't have to be academic papers, it can be anything that helps me to learn more about the topic in the shortest amount of time.
Code. Code is close to useless on paper, I want it to be on GitHub, with a clickable link. All excerpts that you have in your paper, I want them to be highlighted, because that's how it's supposed to be read, there is a reason why everybody but 90 years old professors use highlighting.
Instead of ugly hard to read plots in these papers there are dozens of JS libraries to make interactive plots that can help you show anything you want to show.
Even the mere fact I have to read a PDF off my screen, which I cannot resize to my liking, is annoying. Why must it be paper-first in 2024, when everything is screen-first? Surely there can be rules in these guidelines to make these documents easy to print as well, given how much time one is supposed to spend on correct typographics in LaTeX.