Hi Dan, On Sat, Mar 6, 2010 at 2:12 AM, bump <b...@match.stanford.edu> wrote:
<SNIP> > Of course the documentation in the source files is essential. But > although > there is adequate documentation in the source files for someone who > knows it > is there and wants to dig, you don't get any sense of how to use the > program > from the reference manual. I'm glad you brought this up. Your description above nicely sums up the purpose of a reference manual, and at the same time points out its drawbacks. > I think that for Lie group computations, Sage now has adequate tools > for all the > typical problems. (If there are gaps, let us fill them.) But people > don't seem to know this. > So I wanted to write a tutorial. A tutorial has a different function > from the > documentation in the source files and should be complementary. I personally like the way the Python standard documentation [1] is organized. And I very much like the Sage standard documentation to adopt what works for end users and beginners. Another possible source of inspiration for improving the Sage documentation can be found in the Perl documentation [2]. As regards accessible documentation, I hold the Django documentation [3] in high esteem. > Probably Sage would benefit from an expanded set of good tutorials > here: > > http://www.sagemath.org/doc/ > > To get the Lie tutorial into that page I guess I would edit > > devel/sage/doc/en/website/templates/index.html > > when the patch is revised. Before you do so, for the record, I would like to point out some ideas that have been in the documentation backlog for quite some time. A review of the current Sage documentation shows that it consists of the following: * Tutorial --- a tutorial guide to some of Sage's features that are useful for beginners. * Developer's Guide --- guidelines and policies regarding Sage development. * Constructions --- various short guides along the line of "How do I...?" * Reference Manual --- the Sage reference manual. * A Tour of Sage --- a very short guide along the line of Mathematica's tour. * Numerical Guide --- numerical computation with Sage. * Installation Guide --- how to install Sage. * Three Lectures about Explicit Methods in Number Theory Using Sage --- how to do computations in algebraic number theory, especially number fields and modular forms. What I'm proposing and offer for discussion (and am willing to devote time and energy to the effort) is this. Expand the Sage standard documentation to include the following: * Sage HOWTOs --- consisting of various in-depth documents on specific topics. * FAQs --- a collection of answers to frequently asked questions. The FAQs can incorporate the existing one on the Sage wiki [4], in addition to fleshing it out further. The category of Sage HOWTOs needs more thought. Some chapters in the Constructions Document [5] fit nicely within the category of HOWTOs, e.g. * Linear Programming * Python Functional Programming for Mathematicians But are not all of the chapters making up the Constructions Document written in the style of HOWTOs? I don't know how to answer this question myself. Anyway, if one is to include in-depth guides in the "Sage HOWTOs" classification, I would propose first including the following: * Python Functional Programming for Mathematicians * Sage and Coding Theory [6,7] * Sage and Cython: A Brief Introduction [8] * Linear Programming in Sage [9,10] * Group Theory and Sage: A Primer [11] * Sage and Cython: A Brief Introduction [12] * Number Theory and the RSA Public Key Cryptosystem [13] * Lie Methods and Related Combinatorics [14] I can't help but put the number 13 next to the number theory document because that document deals with prime numbers :-) I can see some advantages and disadvantages for introducing the two new classifications: FAQs, and Sage HOWTOs. Pros: All doctests in the above documents are regularly executed before each release. Having these HOWTOs and FAQs available with every Sage release means that one does not need to download them separately from various websites outside of the Sage infrastructure. For a binary distribution of Sage, all the standard documentation comes pre-built in HTML format. Another good thing (for the Sage website maintainers) is that the help and support page [15] would be less cluttered with miscellaneous documents. Cons: It would add some megabytes to the Sage source and binary distributions. Who is going to contribute time and effort to make this happen? I feel that I should not write such a long email if I'm not going to express my firm willingness to contribute to realizing the above proposals. As a first round of improvements that implements some of the above tasks, I'm willing to incorporate the FAQs into the standard documentation. I'm also willing to create the new category "Sage HOWTOs" and incorporate the following documents in it: * Python Functional Programming for Mathematicians * Number Theory and the RSA Public Key Cryptosystem [13] I wrote those two documents, so I'm more familiar with them than I am with the others. All I'm asking is that people contribute to the reviewing process. Thoughts? [1] http://docs.python.org [2] http://www.perl.org/docs.html [3] http://docs.djangoproject.com [4] http://wiki.sagemath.org/faq [5] http://www.sagemath.org/doc/constructions/ [6] http://trac.sagemath.org/sage_trac/ticket/3624 [7] http://sage.math.washington.edu/home/wdj/cookbook/coding-theory/sage-coding-cookbook.pdf [8] http://openwetware.org/wiki/Open_writing_projects/Sage_and_cython_a_brief_introduction [9] http://www-sop.inria.fr/members/Nathann.Cohen/tut/LP/ [10] http://www.sagemath.org/doc/constructions/linear_programming.html [11] http://buzzard.ups.edu/sage/sage-group-theory-primer.pdf [12] http://openwetware.org/wiki/Open_writing_projects/Sage_and_cython_a_brief_introduction [13] http://sites.google.com/site/nguyenminh2/numtheory-crypto-sage.pdf [14] http://trac.sagemath.org/sage_trac/ticket/8442 [15] http://www.sagemath.org/help.html -- Regards Minh Van Nguyen -- You received this message because you are subscribed to the Google Groups "sage-combinat-devel" group. To post to this group, send email to sage-combinat-de...@googlegroups.com. To unsubscribe from this group, send email to sage-combinat-devel+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/sage-combinat-devel?hl=en.
