William wrote: > I think SAGE might potentially greatly benefit from certain types of new > documentation. <snip>
I have been thinking about the topic of SAGE's documentation for a couple of months now and here is what I have come up with so far. Before one can determine what SAGE's documentation should look like, I think that one must first try to gain an understanding of how the technologies that SAGE depends on ( and also technologies in general ) are going to evolve over the next 20 years. The most detailed projections I currently know of are contained the book "The Singularity Is Near" by Ray Kurzweil and if his projections are even partially correct, the world is going to undergo enormous changes over the next 20 years that will significantly impact SAGE on a number of levels. I highly recommend that the members of the SAGE documentation team read this book ( or an equivalent ) before making a plan for SAGE's documentation so that projections about how SAGE is going to have to evolve to keep pace with these changes can be made. My thought is that commercial mathematics software companies like Wolfram Research are making these kind of projections and I think that this should be done for SAGE too. Moving to more concrete issues, a weakness I have noticed in the documentation for most mathematics software that I have used is that it seems like it consists of shorthand explanations for the underlying topics that are being covered. It feels like perhaps 80% of the documentation is simply missing. The documentation is also not well organized and it tends to jump from topic to topic in a somewhat haphazard way. I think the way that commercial software like Mathematica has overcome this weakness is that numerous people have written books and articles about Mathematica which attempt to explain it better than its standard documentation does. Even though the core documentation is inefficient, I think that Mathematica has still been able to move forward because of the enormous amount of external support it receives. I found Maxima's documentation to be fairly weak and TeXmacs' documentation was incomplete and confusing. SAGE's documentation is actually pretty good and the support on its lists is excellent. My thoughts on making SAGE's documentation even better include developing a detailed topic dependency map for SAGE and then having the documentation conform to this map. When a person initially encounters SAGE, the first thing I imagine them doing is locating the topic on the map that is of interest to them ( Calculus for example ) and then navigating backwards through the map until they reach a level that matches their competency level. They should then work forward through all of the documentation which exists between where their competency starts and the topic they are interested in. Here is an example of the map I have been using to develop what I have referred to in the support list as pre-SAGE educational materials: http://206.21.94.60/tkosan/misc/example_paths_map_v1.0.pdf This specific map contains some topics that are not directly related to SAGE, but hopefully it is still able to illustrate what a SAGE topic map might look like. As for the topics themselves, instead of being presented in shorthand form, I think topic documentation should be more complete with a clear explanation of the fundamental principles that underly the topic along with how SAGE can be used to work with these principles. I have just begun working on the "SAGE Beginner's Tutorial" I had talked about on the support list and the first topic the tutorial is addressing are the fundamental programming skills that are needed to work with SAGE. Even in its early draft stage, I think it is able to serve as an illustration of what I mean about striving to provide clear explanations of the fundamental principles of a topic before discussing more advanced issues that are built on top of them: http://206.21.94.60/tkosan/misc/sage_tutorial_draft_v.26.pdf I also think that the documentation for each topic should have a section for more complete examples which include the context they were drawn from. By context, I mean the type of information that is typically contained in word problems. Here is an example from calculus: "Problem xx: An open rectangular tank is to contain 500 cu. ft. of materials. What is the least possible cost, if the base costs $3 per sq. ft. and the sides $2 per sq. ft.?" What I would like to see in the SAGE documentation is a detailed explanation of a best practice way to model this problem in SAGE and why it is being modeled a certain way and not some other way. I then want to see a set of best practice steps that can be used to solve the problem, along with a detailed explanation of why these steps are being used and not some other steps. One of the conclusions I have drawn from Kurzweil's projections is that technology is going to evolve so quickly over the next 20 years that people are not going to have anywhere near enough time to learn mathematics the way it has been learned up to this point. I think mathematics software will need to become the central tool around which a person's mathematics learning strategy is based and it will be critical that the documentation for this mathematics software be of extremely high quality. The high level of quality will be needed because there is not going to be enough time for people to learn mathematics software through trial and error because of inadequate documentation. People's minds are going to need to have something solid to hook into from day one and then they will need to be given unambiguous and efficient learning paths to follow to the topics that they need to work with. I think the world has already reached the point where its is not what you know that matters, its how quickly you can learn what you need to know. It appears that this principle will become increasingly more important in the near future and I think that SAGE's documentation should reflect this reality. Anyway, I will volunteer to help with developing SAGE's next generation documentation, but I really think that some technology projections should be done as a first step :-) Ted --~--~---------~--~----~------------~-------~--~----~ 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/ -~----------~----~----~----~------~----~------~--~---
