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 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.
