Three sins of authors in computer science and math (1997)

Nowhere in the essay you read does the author criticize presentation of text on the page. He critiques the actual content of technical papers. You are critiquing his use of CSS (or lack thereof).

My view, from math, computing, and computer science is (1) that the author is being too critical and often throwing out a small but good baby with some not very dirty bathwater and (2) that he is not mentioning some larger problems, worse "sins".

Here would be my list of the worst sins or how to avoid them:

(1) A term is a word used with other than a standard dictionary definition. Technical fields are awash in terms. Make sure to try hard to define all the terms you use; with some judgment applied, can omit definitions of some terms certainly well understood by any reader with enough background to get anything from the paper. Poorly or undefined terms can be one of the best ways to lose readers. Here, hoping to get more readers, maybe inviting them into the field, bend over backwards in defining terms, that is, maybe give some term definitions for readers who, really, have little hope of getting much from the paper -- at least, when such a reader gives up they won't blame the author!

In addition, for any term new or relatively new to the field, with some judgment, might also include for the term motivation of its importance and examples of its usage -- i.e., make clear the importance, relevance, value, usage, etc. of the term.

(2) For nearly all acronyms, standard in the field or not, for the first use of the acronym include what it abbreviates. Here to be sure are doing well on this issue, strain and bend over backwards and include, say, even TCP (transmission control protocol), SMTP (simple mail transfer protocol), CPU (central processing unit) -- sure, I'm suggesting bending over backwards. Several slaps on the wrist, an hour in the corner with wearing a dunce cap, and a coating of tar and feathers for each acronym used but not defined with what it abbreviates.

(3) For how to write math, in two parts, (A) and (B):

(A) Take some theorem proving courses from some of the most precisely written texts, say, P. Halmos, Finite Dimensional Vector Spaces, W. Rudin, Principles of Mathematical Analysis, Neveu, Mathematical Foundations of the Calculus of Probability, E. Nering, Linear Algebra and Matrix Theory, Royden, Real Analysis where do a lot of the exercises as homework and where the professor DOES read and remark on your writing. Neveu was a Loeve student at Berkeley. Nering was an Artin student at Princeton. As I recall, Rudin's background was in Austria, although I don't know who his professors were. Of course, Royden was long at Stanford. For more, if have time and insist on some really good examples, read some of Bourbaki.

By the way, on use of we, that is standard. So we might have,

"Given topological spaces X and Y and a function f: X --> Y, we say that function f is continuous provided for each set B open in Y f^(-1)(B) is open in X.

So, that's a vanilla example of using we in mathematical writing.

(B) Do some things none of those texts do: Include some intuitive views, some helpful pictures, motivation via applications in math and also outside math, and outlines of research directions.

There is a lot of question about how appropriate is suggestion (B); in math my guess is that there is no question about the relevance, wisdom, importance, value, etc. of suggestion (A).

For the goal of writing math, suggestion (A) is important: Tough to expect good success without the texts I listed or other texts written with similar care. That level of care is extreme, tough to find and learn, and much tougher to do. Writing math with the care of those texts seems to have been understood and practiced significantly often only after about 1950 or 1940. And for at least one course from at least one such text, DO have the good homework grading of a good math professor.

Personal experience and lesson: While I'm not much interested in being a professor, I have published some papers, and from getting those papers reviewed my guess would be that about half of the reason the papers passed review, and they always did with no significant revision or difficulty, is that I wrote the math with nearly the care and precision of, say, W. Rudin. Point: To critical readers, any lapse in that level of care and precision can be like a worm in a baked apple, perhaps otherwise terrific from brown sugar, butter, etc. Or, might guess that, in nearly any field, the good work is less than 10% of the total, maybe less than 1%, with the rest flawed, maybe as bad as that apple with a worm. In writing math, it is way too easy to be in the bottom 99% or 90% just from the care and precision of the writing, and suggestion (A) is IMHO (in my humble opinion) a good way to have at least the writing quality keep you in the top 90+%.

For math used in computer science, for how to write that math carefully, there are of course examples from D. Knuth.

Another practical point concerning grandmothering is journal editors. Journal editors are often not experts in the specific subfield of the paper and almost certainly won't read much further than the first 1-2 paragraphs. Thus, the first 1-2 paragraphs must, in addition to stating what the paper does, give sufficient context to convince a lazy editor that the topic is important enough to be the focus of a paper in their journal. In my experience, grandmothering is often trying to achieve this purpose.

Blame your browser for being crap at doing the main thing it was created for: Rendering good old plain HTML.

The bigger and more interesting point is how to navigate the world of research where everyone is convinced their way is the only right way. I paragraph-TOCs, but my reviewer insists on including it. This article is an example.

We need a better way to establish consensus for things that can be standardised and we need more taste and tolerance for things where opinions can differ.