Mathematicians do document and comment, that's what papers and textbooks are: commentary on the math. They don't throw out formulae and equations and call it a day. Attaching a full tutorial for every level of reader is tantamount to attaching Stroustrup's C++ books to every C++ program, or K&R to every C program. You wouldn't do that, you'd expect the reader to ask you for references or to seek them out themselves.

> or K&R to every C program.

That's actually doable... ;) K&R is rather terse, what, 1/5 of Stroustrup or something like that. But I digress.

More on topic: there's also a class of programs that DO come with a book attached - or rather, multiple books, for every level; if not included outright in the distribution then at least linked to in the "learn" tab on a homepage. They're called programming languages. So, it can be done. That's all I want to say.

> What is so wrong about attaching additional few pages to every paper that nobody wants to do it? Pages with explanation of the syntax used, even the common bits.

Programs don't do this, why do you expect every math paper to do it?

> Link to external resources with explanations!

This is called a bibliography, every book that isn't so old that it is the definition and paper includes one. In many textbooks there are also appendices which cover (some of) the foundational material. And most include sections (often in the front and back covers) that show the symbols and their names, if not their definitions.

> Programs don't do this, why do you expect every math paper to do it?

Well, I don't. It was you moving the goalpost. I talked about "a few pages", and you made "a book" out of it. I simply don't agree with you here and so I have very little to add at this point, sorry.

> This is called a bibliography, every book that isn't so old that it is the definition and paper includes one.

No. Bibliography is like a list of libraries you depend on. It has literally nothing to do with explaining the syntax close to where it's used.

> appendices which cover (some of) the foundational material.

Ha, ha, ha. No. If it's not front and center, then it doesn't count. I'm sorry, but I'm really tired of this subject. I would be willing to compromise more if that wasn't the case, believe me.

> show the symbols and their names, if not their definitions.

Ok. Putting that on the cover is a bit strange, but ok. That's a nice, but very small, step in the right direction. Please iterate and improve upon it!

EDIT: again, because I missed it at first:

> Programs don't do this, why do you expect every math paper to do it?

Programs do come with man pages! And tutorials, interactive tours, contextual help, and more. Emacs comes with 3 books, and a tutorial. (GNU) libc has a book to it. Firefox has a whole portal (MDN) as its documentation. Visual Studio comes with MSDN and a huge amount of explanatory material. And when it comes down to code, you have auto-completion, go to definition, search for callers; you can hover over a symbol and you get a popup with documentation and types; you can also trace execution, stop the execution, rewind the execution (if you have good debugger), experiment with various expressions evaluated at different points.

The most important difference between math and programming (or CS)is that programmers can (and do) build automated tools that help the next generation of newbies get into programming, while mathematicians can't. It's just that they don't want to admit this is a weakness, and only fortify more in their ivory towers.

TLDR: I just can't see how you can even put math papers and programs on the same scale in terms of accessibility!

> Programs do come with man pages! And tutorials, interactive tours, contextual help, and more. Emacs comes with 3 books, and a tutorial. (GNU) libc has a book to it. Firefox has a whole portal (MDN) as its documentation. Visual Studio comes with MSDN and a huge amount of explanatory material. And when it comes down to code, you have auto-completion, go to definition, search for callers; you can hover over a symbol and you get a popup with documentation and types. I just can't see how you can even put math papers and programs on the same scale in terms of accessibility!

You are comparing big teams and products to a single guy writing a paper intended for a niche audience and to be read maybe a few hundred times if he is lucky. People makes mistakes and sometimes forget to document everything, they try to document everything though as can be seen in their papers where most things are documented well, but sometimes they miss things and unlike code you don't have compiler warnings telling you about it. And given how few people read those papers it isn't worth investing in a team to go through and update all of those papers to properly add definitions for everything they missed.

The equivalent to those programs in math would be high school textbooks, and they are extremely well documented and easy to read in most cases.

> it isn't worth investing in a team to go through and update all of those papers to properly add definitions for everything they missed.

Thank you. There's nothing else left to discuss.

Thanks for understanding, math is a small field without money for things like this, there is no way anyone should expect those niche papers to be as well documented as big programming projects used by millions.

If you still think that is a problem then start some open source organization to fix that. Nobody has done that yet though since so few people care about math papers, but since you feel so strongly about this you could do it, someone has to be the one to start it.

No, I mean, well, it's very understandable when you describe it that way. Actually, I think your post here changed my perception of the problem the most out of all discussions I had on the subject. It made me think about people who are behind the papers. I somehow missed it. Thank you.

(And, sorry for being a jerk in this thread. I said too much in a few places, exactly because I didn't think of innocent mathematicians who might read it. I'm still convinced that there is a lot that math can borrow from CS and SE, but I'm definitely going to argue this differently.)

I wrote one math paper before I went into programming. It is a lot of work, like code reviewing but much much longer. It isn't fun. A big reason I got into programming is because that process is so much work. Of course I, the professor who reviewed it and the professors who looked at it afterwards understood it, but I can't guarantee that someone who hasn't read a lot about research level topology or combinatorics will easily understand much at all. However I doubt that anyone who didn't do those things will ever read it since it is an uninteresting niche topic. I'd be surprised if even 10 people read it fully.

Yeah, I didn't think about it at all - I didn't realize that what I'm saying is basically demanding people to work for free (and on things that won't be useful to anyone in 99% of cases), and that's on top of already huge effort that is writing the paper in the first place. Honestly, I was behaving like people who open tickets in an open source project just to demand that someone implements a particular feature, just for them, and right now. I dislike such behavior, and realizing that I'm doing the same hit me hard :)

Anyway, lots of mathematicians works really hard to make everything as understandable as possible. Learning programming isn't the same thing as learning math. In programming you learn an instruction set, and then you use those instructions to compose programs, therefore learning that instruction set is relatively easy. Mathematics isn't like that at all, instead you just continue to learn ever more complex instruction sets, you don't compose much at all in mathematics because the new instructions typically can't be expressed using the old ones. Therefore learning the instruction set in math is equivalent to learning math, it isn't something you just do once and then is done with it, learning the instruction set is close to the entirety of learning math.

For example, when learning programming you have to learn about arithmetics, pointers, functions and structs. And that is it, now you can program everything as long as you have an API to program against since everything else builds on top of those. That is equivalent to learning algebra in math. You can do a lot of things using algebra, but every new course introduces a lot of new concepts that can't be expressed in elementary algebra. Programming however becomes the art of expressing everything using these very simple instructions, while math is the art of creating instructions that can express things simply.

> Anyway, lots of mathematicians works really hard to make everything as understandable as possible

You just said they don't because it's not worth it. So which is it in the end?

> In programming you learn an instruction set, and then you use those instructions to compose programs, therefore learning that instruction set is relatively easy.

Yeah, sure. Elementary arithmetic, like 22 and so on, is also not that hard to learn. What you're saying is barely scratching the surface of what programming is, then misrepresent it as the whole truth.

It's not that programming is easy. It's just that you can still earn a very good salary without ever touching the harder and more complex parts. People who knew how to do 22 were also well-paid at some point in the past, yet Euclid still managed to write his Elements. You're like an actuary (working under a Pharaoh to count the cattle, let's say) who says that writing Elements is as easy as his current job (you could do it yourself, but you're too busy right now, so maybe later).

> For example, when learning programming you have to learn about arithmetics, pointers, functions and structs.

And then you try to write a JIT for a dynamic (and concurrent, let's say, as Erlang succeeded in this in the last release) language and, with just "arithmetics, pointers, functions and structs", it becomes obvious it's not nearly enough. Then you start reading books and papers and soon you realize that 5 years have just passed. And JITs are not really that complex!

> Programming however becomes the art of expressing everything using these very simple instructions.

Programming is an art of creating new instructions, both out of thin air and out of already existing instructions. The fact that you seem to think "the instruction set" (meaning concepts that have to be understood, I think?) is constant suggests to me that you you're not very interested in history of the field.

> And then you try to write a JIT for a dynamic (and concurrent, let's say, as Erlang succeeded in this in the last release) language and, with just "arithmetics, pointers, functions and structs", it becomes obvious it's not nearly enough. Then you start reading books and papers and soon you realize that 5 years have just passed. And JITs are not really that complex!

I actually wrote a JIT for one of Googles internal machine learning frameworks, so yes. It was used in production for Google search, Google ads etc. Only a very small part of that traffic, of course, I didn't do something huge, but at least I know what it takes to make such systems production ready and performant enough, as these systems are extreme resource hogs. So I know very well what it takes to create a language, parse it, execute it, optimize it and ensure that there are no errors in production and help the researchers who are supposed to use it to debug when errors happen.

I learned programming by just implementing a lot of complex algorithms and systems. I wrote several high throughput http servers using sockets and threads for example. I also got good enough at competitive programming to occasionally place in single digits in some world programming competitions, but mostly double digits. All of that is very easy to understand compared to math, math just forces you to bend your mind in strange ways, programming is super concrete.

I have no doubts that programming will one day get as deep and mindbending as math, physics definitely is for example, but today it isn't even close.

I think the GP post is criticizing the lack of documenting syntax. Math papers tend to document semantics, whereas the understanding of the syntax by the reader is presumed.

Note that the OP is asking about college-level math, not cutting-edge papers.

Textbooks routinely have a list of symbols and their definitions.

But, from my experience, notation is rarely the problem. I’d bet that the root cause of OP’s frustration is lack of understanding of concepts, not notation. (But, of course, it’s hard to say more without specific examples).