This post is from one of several previous incarnations of this site and probably doesn’t quite fit the current format. In a former life this was a group blog and a tumblelog before it became a static jekyll site. If anything looks broken or is worded oddly that could be why. Pardon the dust.
Disclaimer: I don’t actually own a paper copy of this, I’m just in the process of working through it online at djangobook.com. But while I’m at it I just wanted to jot down a few thoughts that are fresh in my mind.
I’d looked at django briefly a while back but had been slightly put off by the templating mini-language along with a few other minor quibbles. Lately though, I’ve been feeling the need to give it a second look. After getting some practical experience with Rails, and seeing the backlash against it play out, I’ve been catching recurring glimpses of django waiting in the wings and rehearsing lines for its role as understudy.
I had planned on ordering the book in the near future but just started in on the online version out of impatience. Unfortunately, it’s turned out to be a relatively disappointing experience. The djangobook website looked like a pretty promising venture when it appeared. Chapters would be posted as they were written, and comments were enabled on a per-paragraph basis, setting many eyeballs to work as cheaply labouring editors and technical reviewers.
I read a couple of the first chapters as they arrived and then left it alone until now, with all chapters accounted for and the finished book finally published. I don’t know what happened in the interim, presumably comments were made, some were taken into account, and the odd revision was made to the text on the basis of these. From the dates on the comments that remain, it appears that any from prior to the release of the physical book have now been cleared out leaving a blank slate alongside the finalised copy.
This is where things start to disappoint for me. The book was released late last year, and in the intervening months a respectable new crop of comments has sprouted up throughout. Unfortunately, a hefty portion of these are pointing out easily avoidable errors. Scan through the text online and wherever you find a paragraph with upwards of 4-5 comments, you’ll find a legitimate complaint. There are simple typos and stylistic issues. There are problems with the over-arching structure of the book. And then there are installation showstoppers where instructions aren’t working in a given environment and readers have had to Google for fixes.
Where clarity is lacking or mistakes have been made in the text the comments are invaluable. Comments that aren’t available in the printed book. The book whose copy had already been finalised. The book which is already on sale.
Ok, books are published with errors. Ok, the authors are developers and not professional writers. They’re just trying to take some time out of their already busy work lives for a healthy stint of product evangelization. There are excuses that can be made. But it seems to me that there is some confusion as to the distinction between the frozen in time print edition and this living breathing web edition.
Is it done now? Are we going to see further updates? Are their political issue issues because the publisher doesn’t want to impair book sales with a web version that’s a superior product? (Although it already seems to be by virtue of the comments alone). Where there are legitimate complaints in the comments it seems like the majority would be fairly quick and easy to fix. So what’s the situation? The waters are muddied further by the presence on the website of an errata page. Presumably it’s targeted at readers of the print edition but, again, without a formal statement clarifying the distinction we’re left to guess.
Aside from the print/web divide there are also issues with the structure of the book in general. It doesn’t feel like much thought has gone into the examples used. We start out building pages which format the time, then we build a database centered on books, then we populate one table only to try out the admin interface using another, next we create a search form for a (still empty) table before skipping off to do a contact form…
When you’re trying to follow along at home it’s just a little too scatter-brained for my liking. Either do a tutorial, or go with a reference, but don’t sit on the fence. And either way, if you’re giving code examples please try to avoid them being reliant on things that you could’ve easily walked us through in earlier chapters. If I can’t type something in and try it out there and then it disrupts the flow of my reading and has me skimming ahead for the next example I can use.
I think the Pragmatic Programmer’s AWDwR has faults of its own, but the structure of the first half of that book is good demonstration of what I’m talking about. It steps you through the majority of what you need to know using an online book store metaphor and maintaining consistency throughout, even adding in a bit of meta-story about the client-developer relationship during production. It may sound like hand-holding, but that kind of attention to detail really makes for smooth learning as you step through the code example-by-example.
The other alternative, of course, is to get out of my way and give me a reference so I can put the pieces together myself. And yes, before you mention it, I know about the documentation at djangoproject.com. Maybe that will be a better fit for me in the long run, it’s just a shame to see such issues with the chosen ambassador for what’s obviously a pretty cool technology.