[Axiom-developer] magic, religion, and pamphlets

[daly]

This was in reply to a private email complaint about pamphlet files. 
These points have been made before in various contexts. They are 
summarized here so we can have a record in the mailing lists.




In reference to pamphlet files there are several points.

THE BEGINNERS MIND

You're not approaching your algebra with a "beginner's mind".

You write the spad code so it is obvious to you. And the underlying
theory is in your area of expertise so it is also obvious. However,
30 years from now someone will attempt to maintain, modify, and extend
the algebra you've written. This person will certainly have a "beginners
mind" with respect to your code. Nothing will be obvious. There will be
intermediate results (e.g. extending the field of constants in the
integration code) which are required by the algorithms but never show
up in the final result. 

If you were to write up your algorithm in a style similar to Knuth's
rather than as a technical paper you might find it easier. Knuth 
"explains" the program to the reader by introducing the decisions
about variables, data structures, efficiency issues, and other topics
before introducing the main algorithms. Thus when the reader reaches
the main algorithm description it is clear why the code is expressed
in the given form. It's the computational math equivalent of the lemma.
Now all he has left to do is explain the main theory.

There are a lot of questions for a "beginners mind". Why did you choose
to build the domain over this algebraic structure? Why are certain
functions exported and others only local? Why are certain functions
conditional? What are the limits of these algorithms? What parts of
the theory are poorly addressed? Where is there room for improvement?





COMPUTATIONAL MATH vs MATH

You even mention that "the code because of necessary data structure and
efficiency issues would not follow the theory exactly". Consider that,
while it may not follow the mathematical theory exactly, it does follow
the computational mathematical theory exactly. You're applying the wrong
metric to the problem. Computational mathematics is not traditional
mathematics. 

The difference between math and computational math is similar to
the difference between an existence proof and a constructive proof.
Both are valid but one is clearly more useful for certain purposes.

And in some sense you're applying the wrong model of documenting the
theory (mathematical papers) to the problem of documenting the
computational theory (pamphlet files).




YOU and who else?

The quaternions were documented in the latest release using a
public-domain, freely available textbook by Tait in the 1850s.  The
file contains hand converted text to Latex and then the pamphlet file
was decorated with command line examples from axiom sessions.  Tait
could have done a better job and given much better and more insightful
examples. However, he's dead. But its a start which we can now shape,
reshape, and improve for our needs.

We do have the good fortune that his work is in the public domain so
we can freely use it. We have the bad fortune of being unable to get
feedback directly from him. Do you want your work to be documented by
a 3rd string mathematician 150 years from now? Or would you rather do
a quality job yourself? If we're lucky axiom will outlive all of us.




PAMPHLETS ARE HARD

And pamphlet files are probably the wrong way to capture this information.
But currently there is no other mechanism. Suppose one writes up an algebra
package of only algebra files and puts it in the system. Suppose there is no
documentation and no test cases. We have no idea if it works and no way
to figure out what it might do, not to mention how to test boundary cases
or unit test the functions. There are no literature references so we
can't even look up the theory.

If all else fails use the "big staple" theory and just attach papers.

Writing pamphlet files, and convincing people that pamphlet files are
a good format and medium for computational mathematics seems to be
about as hard as convincing a student that there are certain
acceptable forms of technical papers and dissertations. Part of their
training as a mathematician is learning to publish according to form.
Part of the training of a computational mathematician is learning to
write literate documentation of algorithms. 



PAMPHLETS CARRY THE "NOW"

Writing computational mathematics documentation as published journal 
articles suffers from the problem of time. All of the algorithms in
Axiom will drift over time as more people make changes. If we don't
document the algorithms and keep the documentation with the code 
we certainly won't document the changes. So the algorithms will come
to represent the collective mindset of several authors, none of whom
spoke to each other, in a multi-generational non-conversation. There
will eventually be no correct reference sources and no clue how this
code actually works. That path leads to code-death.



PAMPHLETS ARE PROBABLY WRONG BUT...

Without SOME documentation the algebra code is magic.
As long as we allow magic we might as well allow religion (pamphlets) :-)

Tim