Ted: Very very interesting. Thanks for the great comments and the offer to help.
+++++++++++++++++++++++++++++++++++++++++++++++ On 7/23/07, Ted Kosan <[EMAIL PROTECTED]> wrote: > > 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/ -~----------~----~----~----~------~----~------~--~---
