, On Mon, Dec 3, 2012 at 1:16 PM, David Roe <roed.m...@gmail.com> wrote: > > > > On Sun, Dec 2, 2012 at 11:59 PM, charles Bouillaguet > <charles.bouillag...@gmail.com> wrote: >> >> I still think that MAGMA's "handbook" is easier to browse than SAGE's >> reference manual (both are supposed to exhaustively describe all the >> functions in the system). One reason for that is probably that in >> SAGE, we auto-generate the manual... >> >> But still, there might be a few things we could do to help, e.g. >> #6495. My generic opinion is that the most frequently used >> mathematical objects should be the easiest to find in the reference >> manual (think of it as Huffman coding...). >> >> For instance, it is close to impossible to find "vector spaces" in the >> reference manual. This has puzzled and annoyed me for a while! I now >> realize that this is because we don't have a "VectorSpace" class, and >> that we instead have "FreeModules", which are more generic. The thing >> is that most, if not all, undergrads looking to play with vector >> spaces will not know that they should in fact look for FreeModule's. >> Wouldn't it be possible to work around that, and make the reference >> manual a bit more "non-advanced-mathematicians-friendly" ? >> >> Comparing with the MAGMA handbook again, I think that their design >> decision to expose "basic rings and linear algebra" as one of the >> first titles of their manual is a very good one. It has certainly >> helped me learning MAGMA quickly... > > > I agree that MAGMA's manual is much better structured than Sage's. Last > spring William funded a Sage Days on improving Sage's documentation; one of > the main goals was to think about how Sage's documentation was presented. > Unfortunately, we had very few people willing and able to attend and the
Yes, it was kind of frustrating. Basically, David advertised it a lot, but at the end of the day, basically few people were available to come to a Sage Days on improving the documentation, even with all expenses paid... If anybody reading this has any experience with how to dramatically improve reference documentation of a big open source software project, please share. One difficulty with Sage is that there is probably no human alive who can really understand all of what Sage does, due to how many areas of advanced mathematics Sage touches, so whatever we do simply can't be a one-person project. In this regard, the scope of Magma is actually much smaller than that of Sage, since, e.g., Magma includes nothing in symbolic calculus and almost nothing in numerical analysis, which are two massive areas. Somebody asserted above that the Sage reference manual is supposed to cover "all the functionality of Sage". However, this is not what it does, and I'm not sure it should. The reference manual covers most of the functionality of the core Sage library, which -- depending on your perspective -- may or may not be a big part of what Sage does (for you). For example, an undergrad recently asked me how to find out about what Sage can do in signal processing, and I definitely didn't suggest that he read the Sage reference manual; instead, I suggested the scipy website. Another example: Cython is a big part of Sage, but it isn't documented in the reference manual. -- William > workshop was repurposed on p-adic overconvergent modular symbols. :-) > > I suspect that if there was interest in running a Sage Days on improving the > structure of Sage's documentation we could find funding. > David > > -- > You received this message because you are subscribed to the Google Groups > "sage-devel" group. > To post to this group, send email to sage-devel@googlegroups.com. > To unsubscribe from this group, send email to > sage-devel+unsubscr...@googlegroups.com. > Visit this group at http://groups.google.com/group/sage-devel?hl=en. > > -- William Stein Professor of Mathematics University of Washington http://wstein.org -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To post to this group, send email to sage-devel@googlegroups.com. To unsubscribe from this group, send email to sage-devel+unsubscr...@googlegroups.com. Visit this group at http://groups.google.com/group/sage-devel?hl=en.
