--- "Page, Bill" <[EMAIL PROTECTED]> wrote: > On Thursday, September 01, 2005 5:34 AM Clifford wrote: > > > > Least anyone think I have abandoned this, I just want to give > > a brief update: > > > > [writing design documentation] > > > > ... so I'll try to cram in all the potentially important > > information. I suspect what I'll wind up with might be > > overkill, but it can always be trimmed down. > > I shall always remember that a famous physicist (Dirac, I think) > once started his presentation at a conference by apologizing that > "he did not have enough time to write a shorter paper" ...
If he didn't, I'm dubious that open source developers will either ;-). > The point being, I guess that it is relatively easy to but down > a lot of poorly organized stuff dealing generally or maybe in too > much detail with partly the wrong stuff, etc. But he made an > apology because he felt that by doing so he was being somewhat > discourteous to his audience. One of his responsibilities as a > writer is to say clearly and exactly what the audience needs to > know and this takes *more* time than being verbose. There are three stages writing a paper goes through: 1) Where you are trying to pull together enough information that you can actually cover what you need to to do a proper treatment of a subject 2) Where you are trying to write up all of this information in a way that makes coherent sense 3) Where you have a good grasp of all the details and essentials of what you have written and can turn your attention to boiling it down to its clear, precise essence I am currently at stage one. Understanding the subtle issues releated to Dimensions, Units, and using them "correctly" is not something I am fully comfortable with, and the first order of business is to get a good idea of what correct is. This involves both understanding the concepts themselves, and expressing them in Axiom - unfortunately I am busy trying to understand the concepts and have yet to move on to the Axiom part. > A related issue is that we need to take account of the fact > that human beings have some built-in limitations when it comes > to appreciating complex subjects when they are presented with > too many unorganized ideas at once. If it is at all possible > we need to choose a mode of expression that is more powerful, > i.e. say more with less but carefully chosen words. This is > often where mathematics ( = 10,000 words) , pictures (= 1,000 > words) and demonstrations ( = 1,00 words) should come into play. Unfortunately, this is only likely in the case of really mature topics. Not to mention that doing this is as much an art as a science, and I think relatively few people in any disicipline have mastered it. > While I appreciate all of the documentation that exists about > Axiom (It is much better than if there was none at all!) but I > am rather afraid that we are already well past the point of having > to apologize to new people who come to our documentation and our > web site to understand as quickly as possible what they need to > know about Axiom. :( Even give Axiom's "30 year horizon" and the > chance that I might actually live that long, I do have doubts that > I will ever end up reading all of the material about Axiom that > we already have. I think part of the problem (certainly I can speak to my own case) is that people don't necessarily know "what they need to know". Axiom is an environment that enforces correctness, and that is going to cause problems for people trying to quickly solve casually framed problems. It's a more subtle manifestation of the reason lab students don't want to record units - half the time they don't KNOW what units the measurement is in, and don't want to try to find out. So I think a lot of times Axiom is forcing people to think about things they SHOULD be thinking about, but want to brush under the rug. I can't really bring myself to consider that a bad thing. We should probably have a way for people to say things like "I'm dealing only with reals, quit bothering me about issues related to all these obscure types!" in settings, but those settings will then be explicit statements of what domains and constraints are in place. This should be well defined always, even in things like physics where they want to get on with it and not worry about the details. Provide a working environment, but that working environment should be based on sound, well defined principles which are programmed and available, even if the user doesn't have to explicitly set them all. There is something I like to call "irreducible complexity" in software, and in ideas and interfaces as well - some things simply ARE hard. Axiom is trying to be correct, and as a result it has to both ask and answer many many questions that are routinely ignored, treated as a matter of course in sub-topics of mathematics, or in some cases not well defined at all. I may be overestimating the authors and designers of Axiom, but at this point I have a feeling that the effort to be fully correct is responsible for much of the verbosity of Axiom. Being precise in meaning and correct in definition is a hard, hard problem. It is probably impossible to meet those goals and remain readily comprehensible, simply because most people don't think about things in a fully precise and correct matter. > I am thinking more and more these days that we have to think > about improving the quality of what we have (and therefore > reducing it's length) while at the same time producing more > quantity. I would actually suggest we start thinking seriously about using/incorporating ACL2 or HOL4 or some such system and using proof logic, since that is the purest expression of meaning I know. The hard part is translating this type of logic into human-friendly English, and that's where I think most of the verbosity comes in. That translation is both necessary and not well defined. > > ... > > Thought we'd get more comment (other than from me anyway) on > > William's overall design ideas - maybe we got too longwinded > > and lost the audience? ;-) > > > > Aw, proving my point above! In fact I did read all 60+ pages, > but I must say that at some point I began to feel like I had > lost the path to enlightenment. :) So that's when I went back > to the first few emails and put Martin's example code on the > web: > > http://www.axiom-developer.org/zope/mathaction/UnitsAndDimensions > > After seeing Martin's idea work almost exactly in the way you > originally imagined that it might, I became less convinced of > of my original presumption that there should be a close connection > between units/dimensions and Axiom domains. Uh oh :-) > Now I would like to see what Ralf sketched in Aldor written and > demonstrated in about this same level of detail and functionality. > > Then perhaps we could code something similar to William's > approach (to the extent that I understand that it differs from > both Martin and Ralf). > > Then after experimenting with these "toy" examples a little, > I expect/hope that I might be able to see it "fall into place". I have a feeling I'll have to play around with things at almost all levels of detail, including various toy implementations, before I can try anything "for real." > Some people might be concerned that writing code too soon risks > freezing-in less suitable ideas, but lately I am beginning to > take a more "extreme programming" point of view: writing code > is in fact the whole point of the exercise. Yes it needs to be > documented and understood, but this is (and will often continue > to be) a moving target. We should be prepared to write, correct, > re-write, factor and re-organize our code fluently while making > an effort to keep it clear, concise and easily understood by > others. We need to think-build-experiment-rebuild-rethink- > build ... in an iterative and hopefully inspired manner. Uh oh :-). I tend to prefer the school of do it once, do it right, and never think about it again - after that just use it ;-). We've got Mathematica, Maple, Maxima, and others to "get the job done" - Axiom's virtues are in doing things the "right way." Ultimately, both approaches aren't mutually exclusive. It just spreads overall resources a bit thinner, but since Axiom is no longer commercial and doesn't seem to have much competition in the "Do It Right" space I'm not too worried ;-). Many of us are still learning which end is up in Axiom (and then asking what it means to be up ;-) so I think things will eventually improve. > Of course this is not possible. :) Our tools and our skill are > not (yet) quite up to this task. But at least in the open > source world, I think it is clear that this approach works much > better than the classical engineering "design, implement, test, > and sell" model. Well, define better - it does produce more code, but I'm not convinced it necessarily produces higher quality code. > There. Now I've probably written more than even I will be > willing re-read and have, finally, illustrated my own point. Hehe :-). > Carry on. Will do - distilling things down to their essence is something that a group of eyeballs is very helpful at. I may disagree about what the scope of "essence" is, but I would like to mention one other principle I have heard over and over in experimental situations: "There is no such thing as too much information. It is possible to function by ignoring irrelevant data, it is impossible to function if you discover data you considered irrelevant and didn't record has suddenly become relevant. Always better to know too much than too little. You are far more likely to underestimate what you will need to know than overestimate." I think it is possible to define user documentation, which keeps it simple and straightforward, and programming documentation which should deal with all relevant issues. I think pamphlets are the place for the latter, and the volumes of the Axiom book the place for the former. Or did I misunderstand this, Tim? Note this is not ment to encourage poor or unclear writing, which is an altogether different matter and something I'm probably guilty of quite often. Cheers, CY ____________________________________________________ Start your day with Yahoo! - make it your home page http://www.yahoo.com/r/hs _______________________________________________ Axiom-developer mailing list Axiom-developer@nongnu.org http://lists.nongnu.org/mailman/listinfo/axiom-developer
