tutorial
tutorial copied to clipboard
DjangoGirls
Cliff hanger not appreciated in a tutorial
The tutorial I used as of 10/10/2015 has an interesting habit of ending a chapter (chapter 13 and 14) on an error case, leaving the fix to the next chapter. Suspense is an important technique in literature, but not in tutorial writing. An already anxious student can only be further intimidated.
One example of where this is happening is at the end of the "Django urls" chapter. You make a file called urls.py and put something in it for the home page saying "Use this view" but don't create the view. Then you're instructed to try to visit the home page, where you get nothing because of the error. The next chapter explains how to fix the error.
I guess the solution in this case would be to move the section about visiting the home page to the next chapter?
Suspense is an important technique in literature, but not in tutorial writing.
Hmm ... this isn't just a technique from literature. It's actually also how you take breaks in TDD without interrupting your (red-green-refactor-)"flow" too much: While you should only ever check in code into version control that passes all present tests, when you leave your computer, make sure that one test remains "red" (=failing) (and don't check that state into version control), so that when you return to your computer, you know where to continue.
While we don't cover automatic testing in the tutorial, having an obvious ToDo pending between chapters can be seen as a similar pattern.
Also, one of the important things to learn during the workshop is that error messages aren't something to fear, but ideally something to guide you (or at least an indication of something that's still to do / to fix).
Is there a way to keep the "cliff hangers" but make them less fearsome?
I think chapters should somehow build upon previous chapters but be by themselves something that is self contained. If an attendee stops somewhere, I wants to start, it will naturally go towards the beginning of the chapter, so having to "solve" the cliffhanger might also affect the flow. I am in favor of removing cliffhangers as well.
It is really discouraging to finish on an error no matter how many times you emphasize that errors are not to be feared.
Another part of a break is to relax. If there's a cliff hanger you can't (fully) break away from it. That's why I'd be in favor of removing them.
