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.

Python 3 Marketing Problem?

I ran across Ted Dziuba's excellent post about Python 3's marketing problem via Reddit:
http://teddziuba.com/post/26426290981/python-3s-marketing-problem

I find his argument somewhat convincing. While I like the multiprocessing module there are times when you just need proper threads. An example: if one of your Python processes is starting other child processes, how can you pass the handle to another Python process and let it read input? I don't think you can (please tell me I'm wrong). Also, Peter Wang commented on Ted's blog that rich client apps can benefit from good threading.

I read the link on Python 3 Q&A which Ted provided: http://ncoghlan_devs-python-notes.readthedocs.org/en/latest/python3/questions_and_answers.html (by Nick Coghlan).

I found 2 things interesting about this.


First, I found it reassuring that it was anticipated that the switch to Python 3 would take this long.

Going in to this process, my personal estimate was that it would take roughly 5 years to get from the first production ready release of Python 3 to the point where its ecosystem would be sufficiently mature for it to be recommended unreservedly for all new Python projects  

. . . . 

If we haven’t put this largely behind us by the end of June, 2014, I’ll be disappointed.

It's just his personal opinion, but Nick is closer to the matter than myself, so it's an interesting data point.

Second, the mention of the work on STM for PyPy. I've toyed with PyPy a very little bit and it's probably the first thing I'd reach for if I had a performance issue with Python. That PyPy may also address the GIL/threading issue is really exciting. I'll be watching this space.

It's an interesting thought, but I'm not sure I agree that learning Python 3 is as risky as learning a new language. I'll reserve judgement on that, I confess I haven't tried it yet. The libraries are starting to move over and in a couple of years the risk will certainly be lower.

Is it worth the effort to migrate to Python 3? I will say: not yet. I'm mostly waiting on Django (though if Flask gets there first...).

I'm going to watch the Python 3 library porting effort along with PyPy's STM work and re-evaluate later. Will I move away from Python if threading never gets fixed? It might be a factor, but alone it might not be enough of an issue as long as there are work arounds.


I wouldn't exactly be heartbroken if Python 3 turns out like Perl 6. Perl 6 stalled (died?) and Perl 5 revitalized in the meantime. That'd be an interesting development for Python, though I hope the Python community wouldn't dry up in the process.


Meanwhile, it looks as though Python 2 will still be viable for a long time.