On Dec 10, 2007 11:19 PM, root <[EMAIL PROTECTED]> wrote: > > >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
speaking for myself only: I think Sage is documented as best as it could - but of course doctests should be improved and more documentation written. But as to literate programming, it's a social thing - if people don't want to use that (for whatever reason), one should be very, very careful when imposing it. I think it's essential that people feel motivated to work on Sage, and I think they are. Also, one should imho learn from very successful projects, like the kernel of linux. I love Linus quotes: http://en.wikiquote.org/wiki/Linus_Torvalds My favourite is: Talk is cheap, show me the code. But the one that applies to the sittuation you are writing about is this: Nobody should start to undertake a large project. You start with a small _trivial_ project, and you should never expect it to get large. If you do, you'll just overdesign and generally think it is more important than it likely is at that stage. Or worse, you might be scared away by the sheer size of the work you envision. So start small, and think about the details. Don't think about some big picture and fancy design. If it doesn't solve some fairly immediate need, it's almost certainly over-designed. And don't expect people to jump in and help you. That's not how these things work. You need to get something half-way _useful_ first, and then others will say "hey, that _almost_ works for me", and they'll get involved in the project. Ondrej --~--~---------~--~----~------------~-------~--~----~ To post to this group, send email to sage-devel@googlegroups.com To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/sage-devel URLs: http://sage.scipy.org/sage/ and http://modular.math.washington.edu/sage/ -~----------~----~----~----~------~----~------~--~---
