On Friday, December 5, 2014 1:08:14 PM UTC+1, Jori Mantysalo wrote: > > > Having documentation arranged by technical implementation is also bad. > Having TESTS-section shown for normal user is bad. Having is_lattice() on > different page that is_meet_semilattice() is bad. >
Seconding this. Mixing tests and documentation has its benefits, but it also severely reduces the signal-to-noise ratio for non-developers. In most sections of the Sage reference manual, there is no preamble explaining the mathematical context, and no indication of what the most important methods are (it can be hard for the user to find the right method in an alphabetical list that spans several pages). The structure is sometimes strange: for example, "Solving ODE numerically by GSL" is listed under "Symbolic Calculus"... and on the other hand "Numerical Optimization" is listed under "Miscellaneous Mathematics". Maple/Mathematica/Matlab generally do a better job of grouping functions logically by subject area, listing *relevant* examples, and allowing the user to find related methods easily. Another weakness of the Sage reference manual is that the doctest examples only show text output -- the Ma's examples often show graphical output, which can be a great help. Fredrik -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at http://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
