On 12/03/2012 04:45 PM, William Stein wrote: > > 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. >
The existing thematic tutorials sort-of address this problem: http://www.sagemath.org/doc/thematic_tutorials/ but there are far too few of them. I would suggest creating a magma-like hierarchy of thematic tutorials, one for each branch that Sage supports. The tutorials could link to individual pages of the reference manual, and should go through most common tasks that people might want to do. It should also have brief translations for users of other CAS software. See Rosetta Code <http://rosettacode.org/> for an example of this done well. -- 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.
