Documentation, Documentation, Documentation

Steve Ballmer is famous for walking around on stage chanting "Developers" over and over again. If you haven't seen it, go search YouTube. It's... interesting.

After some thinking on it I feel like chanting "Documentation" in a similar way.

Well... maybe not, but I'm coming to more fully appreciate the role of documentation.

I read this so long ago I can't be sure of where I first encountered it, so I can't give proper credit, but the argument goes that it doesn't matter how clever your code is if no one can figure out how to use it. I've personally experienced this a number of times without noticing it.

The quality of Python's documentation was a factor in my starting to favor Python over Perl around 12-13 years ago.

I liked TurboGears, but ultimately ended up using Django more. The docs were a factor.

I'm really intrigued by Flask, largely because the docs are not only informative on Flask itself but also contain some good advice on web development in general.

I've encountered this a number of other times and often just taken what seemed the most natural path. It's interesting to think what a big factor docs have been.

I've long evaluated the quality of my own work based on the efficiency of the code, the size of a web page over the wire, the simplicity of the design... but what about documentation? But then, I make web apps, and a web app shouldn't need a manual like a development framework would (except maybe for operations/deployment), and no one needs to look at a manual for an iPhone. Sometimes a screencast is more appropriate. So maybe "approachability" is a better word.

Interestingly volume isn't what you necessarily want. I'd take a screencast over reading 5 pages any day and a short PDF over a long PDF (as long as it has what's needed). The Flask docs as a PDF weigh in at 277 pages. Compare that to Django's 1,174 page PDF. While Django does a lot more (and hats off to the team for making sure it's all documented) Flask feels more approachable. I'm looking forward to trying it out.

I've been working on a Django project for a while that has a pretty complicated set of models and a lot of customization in the admin. Some of the users of the admin are not too technical. I've been thinking that I'd like to integrate a YouTube channel of howto-style screencasts right into the admin.

Approachability is a huge factor in making something that's really great, and that's what I'm after.