Tutorial Improvement Ideas

Impressions from sprint at TAU 2008-08-17

(See SprintIsraelAugust2008.)

Overall

• The "experienced" among us didn't get what we're griping about, but the beginners, who were tasked with "testing" the tutorial, unanimously declared the official tutorial painful: confusing, distracting, tedious, way too long (none of us got past part 2!).
• Impatient: we want to see something "interesting" immediately (more or less).
• User controlled dialog: don't lead us by the nose, but give us a foundation (say, demo) to toy with and answer our questions when we ask them.
• Domain model discrepancy (paradigm shift?): we've done frameworks (and CMSs) before, you know, even in Python; what's all this up front hassle running commands at the shell, and declaring models?! Yeah, sure, we trust it all makes perfect sense and we'll wonder how we ever lived without it soon enough, but, right now it's all magic. Scary, ugly voodoo. Can't we postpone that?
• Drupal got mentioned many times: wait, hold it, we're not comparing it to Django, just that the first time experience of installing and beginning development with it is very impressive. Inspiring. Remember Jottit? Would be nice...

Specifically

• Add a walk through of the ./manage.py syncdb thing, just to make newcomers less surprised at the questions the syncdb process will ask. Especially the superuser creation. Woot?
• Add some explanations about the usage of 'classes' to define a model: it is not clear whether these are "real" classes, as in datatypes, or magic used for declaring fields in the RDBMS. At least explain that they're equivalents of entity-relationship models? At least initially?
• The tutorial seems to walk a new user through a data model aspect of Django, but what if my Web application is (more) process centric than data centric? Say, if we had REST in mind, and imagined an "Hello World" sort of demo echoing or transforming requests to responses...? Maybe persistence should come later?