Thanks to the clever gist-it plugin, the source code (on Github) is directly displayed on the dokuwiki pages. While browsing the source code examples i realized that i need to re-write most of them. It's not that they are broken or do not work with python2.7 - it's just that i need to make them shorter and better.
Working with git / github is really a joy. I can now update the source code examples without even bothering to update the dokuwiki pages at all.
My source code examples tend to be around 1000 lines long … far too much for a traditional paper book. The joy of publishing on a wiki is that i can make my source code examples as long as i want - a virtual “page” can be one kilometer long. apart from needing longer to load into the browser and making scrolling / navigation more cumbersome there are no limits.
However there are limits in the user experience. I noticed that it is best to put long source code examples at the end of a (html) page and not at the beginning. While it would make more sense from a logical point of view to first see the code and than read a discussion about it i noticed that few readers bother at all to scroll down to check if there comes anything interesting below the source code. So i put all text and discussion above the source code.
While teaching kids game-programming using ThePythonGameBook i noticed that sometimes a student want to modify an existing game or source code example without bothering to read much more pages. The students usually create little games out of the source code examples, first changing graphics, later changing variables like movement speed in the code and finally altering the games completely. This is the point when i think “that is cool…. i need to put that into ThePythonGameBook”. The problem is that there is never a end for an example games .. there is always something more to add, a new feature to append, until my python code expand way beyond the 1000 lines limit. While there is no shame in writing long python code i feel that a source code that is too long to read and understand comfortably has limited education value.
At the moment i try to store the evolving, bigger games outside the tutorial pages, in a special section of ThePythonGameBook called :en:resources:games. (The majority of my game-projects are not in the wiki but on my harddisk, begging for my time to polish them into a useful state).
Sometimes it would be cool while reading about a topic, - like: displaying text in a pygame window - to get more and more information about this specific topic, going deeper and deeper into detail and seeing more and more complex applications of this topics. Sometimes however a topic is not interesting at all and a page about this topic should only contain the absolute necessary minimum to enable the reader to continue with different, more interesting topics.
If you ever browsed aimlessly in wikipedia articles (or zapped throug TV channels) you know what i mean.
At the moment the pygame tutorial of ThePythonGameBook is one-dimensional, organised in steps (pages), where usually one step is needed to understand the examples of later steps.
What i dream of is a 2-dimensional learning path, where the reader can go page after page more into the detail of a interesting topic while still being able to skip less intereting topics. If on a “deep detail” page wisdom from other topics is needed thos topics should be referenced.
I'm not sure how to implement this dream (learning paths ? only one big alphabetical index ? ) but i'm sure that writing a wiki will make it possible.