Skip to main content
Post Made Community Wiki by S. Carnahan
Source Link
Gerhard Paseman
  • 13k
  • 3
  • 32
  • 63

There are so many things to say here. "The concept of 'well' depends on the (position of the) observer." "Don't just involve the reader, recruit them!" "Reading code is more boring than running it." "Is it really proved if it takes a computer?" Tempting as it is to address these and other points, I will elaborate on just one: recruitment.

A good paper informs, but a well written paper inspires. Imagine that you want someone to not only verify your result but extend it. You should not only explain your work with utmost clarity, you should also indicate ways in which your work could be verified or extended. Ideally you have done some of this verification or extension yourself, and left some of the fun of (re-) discovery to the interested reader.

If you can encapsulate the ideas of the Mathematica code into a paragraph, that makes the paper more approachable than presenting a block of well commented code. My opinion (as a reader, not as a professional writer) is that code listings are best left to an appendix or the end of the paper. Only if you are writing an extremely literate program, where every subroutine teaches some mathematics to the reader, do you include it in the paper. Describing how the program performs in a run without explaining well why each computation branch was chosen has all the thrill of watching paint dry. Instead, try to challenge the reader to code with you, by describing the relevant portion of the computation, and then you presenting your solution and subtly asking the reader to come up with code that is good or better.

I have no examples that apply directly to your situation. For inspiration, I recommend the New Turing Omnibus by A.K. Dewdney, which is a collection of short articles in computer science. If you can write the core of your paper in the style of one of these articles, you can at least get people to read and understand the core, and leave the less exciting stuff for a series of appendices.

Gerhard "Doesn't Always Remove An Appendix" Paseman, 2020.06.25.