[Axiom-developer] Re: [sage-devel] Re: Fwd: SAGE

[root]

>Re-reading Tim's post I think you're right, and that I misunderstood
>what Tim was writing.  I certainly agree that it's important to do the
>"boring" stuff, though I think the best strategy is to find people for whom
>the boring things are NOT boring, e.g., you cite doing releases as
>boring, but I assure you certain people -- e.g., Michael Abshoff --
>find them to be extremely exciting "I was born to do releases", he
>said in irc yesterday; and documentation, that may be boring to
>you, but David Joyner passionately loves writing good documentation,
>and I've seen other people, e.g., Emily Kirkman put quite a bit of
>passion into creating various nice docs for Sage.

Ah, documentation. Axiom has the "30 year horizon" view and one of 
the critical points is that the mathematics needs to be documented
(literate programs, ala Knuth is our choice). I see a lot of python
code that I can reach with 
  foo??
but it seems to have 2 flaws. The first is that I don't see any
documentation of the mathematics or the algorithms except for the code
(THIS is computational mathematics?). The second is that a lot of the
code I've looked at is simply cover functions for other, undocumented
code (e.g. set up the parms and call pari).

Coming back to my original point, the mathematicians don't feel it
is THEIR job to document their mathematics or their code. If you're
lucky (and it is poor luck anyway) you might find a reference to a
published paper. However, the paper does not describe the implementation,
it is likely published in a pay-per-use publication, and it has the
copyright tied up so nobody can use it to document the code. The
academic mathematician, having gotten his "publish", gives the code
away. Many years later nobody has a clue why it works or doesn't work.
How can we expect to maintain and extend such code in 30 years?

We need to raise the level of quality for computational mathematics
so that we EXPECT a computational mathematician to fully document the
mathematics and the source code. We need to create the expectation 
that the documentation IS part of the JOB. This isn't a job "for
somebody else". And it is critical to the long term success of the
project.

And we won't even mention regression test cases, identifying boundary
conditions, estimating the time and space complexity, or any of the
other primary tasks of computational mathematics.

If the mathematics isn't documented then the job falls on your desk.
Good luck with that.

Tim