As many of you may have already noticed, Ondrej and I are presenting a tutorial for SymPy at SciPy 2013. See http://conference.scipy.org/scipy2013/tutorials.php. We look forward to seeing all of you who are attending the conference there.
My hope this year is that we can improve our documentation in SymPy along side the tutorial. Therefore, I would like to write all the main tutorial materials in the SymPy docs, either in Sphinx or as IPython notebook examples, and then just modify those for SciPy. The first place to start is with the main SymPy tutorial, which is currently at http://docs.sympy.org/dev/tutorial/tutorial.en.html. I don't really like it. - It feels outdated. For example, the download instructions refer to a version of SymPy that was released in January 2008 and a version of Python that we no longer support. - The examples are out of date. Reading it as someone who is highly familiar with SymPy's current feature set, it very much reads like something that was written for a reduced feature set. For example, I think when the tutorial was written, the "functions" represented the almost all of the special functions implemented in SymPy. But today, dozens of special functions are implemented. And the general API for working with them (expand_func()) is never mentioned. - It doesn't read like a tutorial. There are two issues here. First, the content feels scattered. It should focus on elementary features, and work its way up in a linear fashion The features it introduces at each stage should be based both on the level of the reader at that point. And it should introduce the features that we know are important. In other words, the tutorial should teach not only key *features* of SymPy, but key *idioms* of SymPy. Second, it reads like a collection of API references, which have been compiled together to give an overview of the main features of SymPy. A good tutorial should be narrative documentation. I would say roughly half of the vertical space of the document should be English text, with the other half code examples. I think we should emulate the official Python tutorial in this regard (http://docs.python.org/3/tutorial/index.html). It has a lot of features that I like - It reads like a book. You could sit down with it and read through it, and get a good feel for what Python is and how it works. - It doesn't dwell on unimportant (to beginners) details. That is what the API reference is for. Compare the tutorial entry for the "for statement" http://docs.python.org/3/tutorial/controlflow.html#for-statements to the API reference http://docs.python.org/3/reference/compound_stmts.html#for. The tutorial explains the basic idea and motivation for the syntax, gives a simple example, and gives advice to avoid a simple gotcha, and that's it. It uses basic English words, and it written in a light-hearted way (like "For example (no pun intended)"). The API reference is completely different. It is very specific. It starts out with the grammar specification, and then lists all the nitty-gritty details that you might come across if you are an expert Python programmer and push for statements to the max, like how the statement is executed, what exact conditions can cause the loop to break, including "break" and "continue", and the iterator raising StopIteration. It talks about the esoteric "for else" construct. It details exactly why you cannot modify a list while looping through it. Beginners do not know (nor should they care) about advanced features like StopIteration or "for else". All they need to know is that you write "for element in list", and that you should not modify a list while you loop though it. - It shows proper idioms. A common antipattern for people who learn Python who already know Java or C is to write something like for i in range(len(a)): print a[i] instead of just for i in a: print i The only example code in the tutorial shows the proper idiom. I also like how it uses the Fibonacci sequence, much like Wikipedia, but unlike every Wikipedia article I've seen, it defines it in the logical, non-recursive manner. - It introduced things in logical order. First introduced are the most important operations, like addition, and print(). Then it talks about the most important control constructs, like if, elif, else, for, and while. This isn't to say it's perfect. I would have taken more care to avoid antipatterns, even explicitly mentioning them and discussing why they are bad. I also would have left some features out, like lambda. A document that is closely related to all of this for us is the Gotchas and Pitfalls document. We should think about how to incorporate that into our tutorial. So I am soliciting initial feedback on ideas to make it better. I am open to both very general and very specific suggestions. Over the next couple of weeks, I will then create a pull request with a rewrite. By the way, on a technical side, what should we do about the tutorial translations? If things go according to my plan, the current translations will become completely obsolete. Should we scrap them completely until new ones are written? Should we leave the infrastructure in place, or scrap it entirely? Aaron Meurer -- You received this message because you are subscribed to the Google Groups "sympy" group. To unsubscribe from this group and stop receiving emails from it, send an email to sympy+unsubscr...@googlegroups.com. To post to this group, send email to sympy@googlegroups.com. Visit this group at http://groups.google.com/group/sympy?hl=en-US. For more options, visit https://groups.google.com/groups/opt_out.
