Hi William, On Sat, Oct 30, 2010 at 12:22 PM, William Stein <wst...@gmail.com> wrote: > Hi Sage-Devel, > I'm curious if people are getting emails like this...
First, a confession on my part. I received such an email in the last 24 hours, asking me to be a reviewer of the proposed book on Sage. I have read through the proposed outline of the book and the reviewer guidelines. And I agreed to be a technical reviewer. > (I don't have anything to do with this PacktPub project. Generally, I think > it is best for people to write documentation for Sage that can be > distributed with Sage, and is organized using Sphinx, etc.) Let me explain why I agreed to be a technical reviewer of the proposed book on Sage. Unless the Sage project has a dedicated documentation team, or people in the Sage community decide to increase their documentation output, we won't see any significant improvement in the near future on the current state of documentation on Sage. Software developers need to move beyond the mantra, "The documentation is in the source code" and learn to be professional communicators, not just professional programmers. A person may be a brilliant programmer, but without sound communication skills (including writing skills) it can prove very difficult for other people to understand and maintain their code. It's the documentation written by the writer of a function that documentation writers look through in order to gain an understanding of that function. The next step is to look through the source code of the function to gain a deeper understanding. Good documentation can make a huge difference between spending hours trying to understand a function or spending a few dozen minutes. Fortunately, the current state of the Sage standard documentation is very good. The documentation is open source. There is the official tutorial, an installation guide, a tour, a list of thematic tutorials, etc., all dedicated to guiding beginners through the vast number of features in Sage. We are grateful to all those who have contributed to the standard documentation. We are also grateful to anyone who is contemplating or is writing a book on using Sage and getting that book published through a publisher and locked behind a pay wall. An author's prerogative is that she can decide whether to contribute her written work to the Sage standard documentation, or to have the work published by a publisher. Let's not forget that this is another way to help spread the words about Sage, even though the work would be behind a pay wall. Having a book on Sage published by a publisher can lend a lot of credibility to the Sage project. I'm happy that some publishers are now open minded enough to publish books licensed under the Creative Commons or the GNU Free Documentation License. Examples include: * Charles M. Grinstead and J. Laurie Snell. Introduction to Probability. 2nd edition, AMS. http://www.dartmouth.edu/~chance/teaching_aids/books_articles/probability_book/book.html with .tex source files * Victor Shoup. A Computational Introduction to Number Theory and Algebra. 2nd edition, Cambridge University Press. http://www.shoup.net/ntb/ * Allen B. Downey. Python for Software Design. Cambridge University Press. http://greenteapress.com/thinkpython/thinkpython.html with .tex source files I think we should embrace the proposed Sage book by Packt as an opportunity to proselytize Sage. We need to accept that different people have different convictions concerning how to publish their writings. Some like to put their writings behind the traditional pay wall, some don't. Free software needs free documentation, and I'm putting my money... err... words where my mouth is [1]. [1] http://code.google.com/u/nguyenminh2/ -- Regards Minh Van Nguyen -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
