Sage documentation quality initiative
Since Harald Schilly started a discussion on documentation quality for Sage at sage-devel, documentation for Sage has been on the path of improvement. Officially known as the Sage Documentation Project, a major objective of this project is to produce various types of documentation that cater towards Sage users with different levels of experience. Here’s a tentative list of different types of documentation together with some explanation of what each one should be, shamelessly stolen from Harald:
- Howto: A basic step-by-step guide with screenshots that walks a user through some process. This can be about installing Sage under various operating systems, working with the Sage notebook, etc. A howto should aim to be easy to use for users not familiar with the process described in the document, it should be straightforward, and probably often updated to account for changes in the latest release of Sage.
- Tutorial: A tutorial attempts to explain a topic, walking a user through on how to do something. For Sage beginners, this can be about studying a first course in linear algebra using Sage, or how to obtain various types of 2-D and 3-D plots, etc. For intermediate to advanced users, a tutorial can cover domain specific topics such as exact linear algebra, algebraic number theory, elliptic curves, curves and surfaces defined by differential equations, etc.
- Guide: This should be more general than a howto or a tutorial. For example, it should explain background knowledge and show how to apply that information when working with Sage. Guides can cover various (good) coding techniques for Sage, on extending Sage’s functionalities, on code optimization and runtime performance, etc.
- Examples: A document on Sage examples specific to a topic. Docstrings for Sage functions contain many examples, which are there as doctests to ensure that the functions work as claimed in its documentation. So a document on Sage examples should cater towards a particular topic, with possibly discussion on advanced features as well.
- Teaching: Sage specific materials such as books and notes that are used in teaching.
For example, we can write a document on coding styles that covers the procedural and object oriented styles, or a style specific to Python programming. Often in studying cryptography, students need to obtain the ASCII encodings of a string of English capital letters and concatenate the encodings into another string. First, we can use something similar to the following code snippet to show how that can be accomplished:
sage: m = list("HELLOWORLD") sage: S = list("ABCDEFGHIJKLMNOPQRSTUVWXYZ") sage: for i in xrange(len(m)): ....: for j in xrange(len(S)): ....: if m[i] == S[j]: ....: m[i] = j + 65 ....: sage: m [72, 69, 76, 76, 79, 87, 79, 82, 76, 68] sage: M = "" sage: for i in xrange(len(m)): ....: M += m[i].str() sage: M = Integer(M) ; M 72697676798779827668
Then we present an alternative method with another code snippet such as the following, which has been suggested by Martin Albrecht.
sage: m = "HELLOWORLD" sage: m = [ord(e) for e in m] ; m [72, 69, 76, 76, 79, 87, 79, 82, 76, 68] sage: m = ZZ(list(reversed(m)), 100) ; m 72697676798779827668
Of course, these are just examples. I’m sure other people have more clever and compact ways of doing the same thing.
In other news, Rob Beezer is working on a set of notes for his students. By the end of that course, we should have a set of notes that incorporates Sage in teaching abstract algebra. Members of the Sage team have started to collect various past and present talks on Sage. This list of Sage talks can be found at the Sage wiki. It may or may not be an incomplete list of Sage talks, since it is up to people to add information on Sage talks to that list.
Now that the documentation project has been started, let the typing begin.