I would vote for putting that content in the "Guided Tour" part of the tutorial. I think the variety of documentation would be a little too fragmented otherwise. In my limited experience so far, new users of sage can already be confused about where they should look things up.
-Marshall On Jul 23, 5:51 am, "David Joyner" <[EMAIL PROTECTED]> wrote: > 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 [email protected] 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/ -~----------~----~----~----~------~----~------~--~---
