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.
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.
You are not the audience for an academic research paper. The audience is other researchers who understand the norms of the field, and are used to the notation and idiosyncrasies.
Re: code. I don’t think any research paper in any field of CS includes source code verbatim in the paper, it’s usually snippets like you want. Sometimes source code is not linked from the paper, but that’s a different issue, and common in industry too (eg closed source code).
Re: references, it’s not about explaining a topic (though that happens sometimes), it’s about providing a pointer to a resource that a researcher who already knows the research landscape can go look at and confirm that yes, the claimed fact is indeed in a previously vetted resource. That is, it’s more about provenance than explanation.
Re: optimizing for PDF output as opposed to optimizing for, say, HTML output/web reading, I only have this to say: I can easily read papers produced 30 years ago in PDF form. I cannot say the same for some websites even 5 years old.
> 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 say that this is less applicable to math than other topics, which is funny—as a mathematician, I'd think that it's more applicable! In the strictest sense of the word, the purpose of a math paper is not to allow others to get information from it, though of course a good math paper will do that. The purpose is to show definitively (in the very strong mathematician's sense of the word, stronger even than the physical scientist's sense) that something is true. Especially for the first proof of an ‘obvious’ fact like, say, the four-color theorem, filling in all the necessary rigor can be at odds with clarity. That is, it is exactly when one is tempted to skip over some point with an appeal to the reader's intuition that one must most carefully fill in those details. (Lots of wrong proofs of the four-color theorem came from explicit or implicit appeals to mistaken intuition.)
I don't see where we disagree. That's pretty much exactly why my points are less relevant for math papers: they are supposed to be self-contained. And while the result is sometimes interesting and can be put into TL;DR, I'd say in the most cases the entire point is reading the proof. No, I mean there definitely were cases when I was just wanted to see the final formula and skip the derivation, and I'd absolutely want it to be in the abstract as often, as possible, and I suspect that many math papers could be improved by using a better media than a LaTeX pdf file, but, as you said yourself, for math, it mostly isn't about informing me about the result.
It is for most other fields. Basically, in the majority of cases the entire paper should be reducible to a couple of sentences that are useful on their own, which I'd like to read in (or rather instead of) the abstract, and the rest 50 pages of the paper should be a detailed report of why is it reasonable to believe you didn't lie (intentionally or not) to me in the abstract, by explaining the exact way to reproduce it, with providing as much data as legally possible. But the insufficiency of the content in your typical research paper is another topic, and much more complicated, so I wasn't going to start about that again, I only raised the points about the format, since that's what the thread is about.
> I don't see where we disagree. That's pretty much exactly why my points are less relevant for math papers: they are supposed to be self-contained.
I'd certainly disagree that math papers are supposed to be self-contained (at least they are not supposed to be completely self-contained, or else they'd balloon to ridiculous size), but I think I misunderstood your comment:
> 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.
I read it as "it is less applicable to math papers than other academic papers that they are not easy to get information from." I think, based on your follow-up, that you meant instead "it is less applicable to math papers than other academic papers that they exist for getting information from." My apologies for misunderstanding.
The main reason academic papers exist right now is simply because academics need to publish papers, in ever larger quantities. It's publish or perish, and it gets a little bit worse every year. The peer review system is a bit of a farce. Sometimes it works out, but there are loads of papers that get published simply because the author is well known.
Papers used to be better. At least in my field, the quality really dropped off in the mid to late 00's. Most of the very best papers that I've read---at least, in terms of writing---were written in the 90's or earlier. I think the increased pressure to publish coupled with people being constantly distracted by computers and other forms of media are to blame.
Depending on what your interest is, you may be better served by a textbook. Or if it's something very specific, just contacting someone by email and trying to have a chat with them.
That said, most of the techno-improvements you suggest (clickable links, interactive plots, etc) are basically worthless. Good writing and good presentation can be accomplished on a typewriter with hand-drawn plots. Communicating technical ideas well requires the author to think carefully about how they'll present their thoughts, which gets skipped over in most cases.
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.)