Python Web Framework Comparison: Documentation and Marketing

by Noah Gift

I haven't read many RSS feeds lately due to time constraints from writing a book, but I came across this post by Adam Gomaa, by way of some of the responses from Jonathan LaCour's blog.

If there is one thing to learn from the endless, and pointless, comparisons of frameworks in Python, i.e, popularity contests, it is that the most important things for a web framework's popularity, in order, are:

1. Documentation
2. Marketing

In a popularity contest, the "best" framework, is going to have the best documentation, and the best marketing, like tons of screencasts, etc. Every other discussion is an exercise in futility. If you want to be home coming queen, people have to know who you are, or they won't vote for you. One of the reasons why Django is considered the most "popular" or "best" framework to many people, is that the Django people did an incredible job of documentation, and marketing.

While Adam brings up some very valid points in his criticisms of Turbogears and Pylons, he ultimately misses out on the real problem and the real solution. While I also like to find reasons to stretch my intellectual muscles and use legendary books to compare and contrast ideas against real world problems, it doesn't work for this comparison.

The real problems doesn't involve fancy computer science terminology, or "Conceptual Integrity", it involves something much more mundane.....documentation. It is a known fact, that smart people, often the very smartest, don't like to document their work, as they are too busy "inventing", and being mad scientists. I am quite certain, that core Turbogears and Pylons developers, and power users, like Bob Ippolito, know how to do things that are unbelievable, but creating bulletproof documentation is tough work. Documentation is a job, and that is why millions of technical books are published making millions of dollars per year. If you consider documentation to be full time job, then people need to get paid to do it properly.

The reason why everyone doesn't have killer documentation and marketing, is that it is perhaps, the most difficult part of being, "in the framework business". Documentation is grunt work, plain and simple. To quote Bruce Lee, "I fear not the man who has practiced 10,000 kicks once, but I fear the man who has practiced one kick 10,000 times." In a similar sense, I fear not the framework that has 10,000 features, but the framework that documents one feature 10,000 times!

Of course, ultimately, a popularity contest is mostly meaningless for people who actually develop in a specific framework and make it their job, unless they are consultants for hire who only build a "insert framework here" websites. As anyone who has attended a 10 year high school reunion can attest, being "popular" isn't always best, but due to human nature they will always be confused. Look at all of the "quiet", corporations, all over the world, that just do Plone development, they are so busy making money, the framework issue must seem like background noise.

Also, it is interesting, but not surprising, that Zope 3, ZODB, Plone 3, and Grok are virtually non-existent in discussions about Python Web Development, in some circles. I wonder how anyone can feel comfortable getting into a massive diatribe on Python Web Development and completely dismiss any discussion about Zope related technology. Listen to the people who write the PEPS. If someone has gotten more than one PEP approved then their opinion is worth 1 million times the regular joe. Last time I checked there are only a handful of people who can say that, Phillip Eby, being one of them. He seems to think Zope is relevant, why don't you?

Another troubling thing I see when Python Web Frameworks are brought up, is a lot of discussion about people writing wiki's and blogs, etc, in the hot new framework. I suppose I should probably bring up that fact that Plone 3 is one of the most kick*** Content Management Systems on planet earth, see PyATL. If you want a blog, install Plone, if you want a wiki, install MoinMoin, or Plone. Unless you want to learn about writing a CMS or Wiki, you are essentially, self-gratifying yourself, to put it diplomatically, by recoding a solution to a problem that has already been solved.

Finally, I think WSGI is going to change everything, because it is about reusing components and products. Some of the current web framework comparisons are just silly. It would great to live in a world in which the real issues are discussed like, "My documentation kicked your documentation's *ss!". He who wins the documentation and marketing, wins the hearts and minds! To steal from a famous political campaign, "It is the documentation stupid!".

Noah's Personal Blog
OS X Automation

AddThis Social Bookmark Button


Eric Larson
2007-12-31 13:36:00
I think one of best advantages of frameworks is they allow easier rewrites. When I used to code PHP I always tried to use reusable applications, but always ended being frustrated with how much work it was to integrate. A framework makes it possible to write code quickly and efficiently, so it would make sense to rewrite blogs, content management systems and anything else using your favorite framework because you have the opportunity to make it exactly what you need without the cruft of generalizations found in a full fledged application. From the users perspective this can be much better as well because the application can be tailored to fit.

The benefit of WSGI is that you can create custom applications and assuming the components are created via middleware, you can easily reuse them. WSGI makes for an excellent plugin framework and even if you can't use middleware out of the box, the framework again gives you the tool to learn from the available middlewares and write your own.

I suppose the concept is closer to reusing ideas over actual code. In a way this is similar to de-normalizing a database for performance. In this case, you don't mind rewriting code because it is results in faster, more customized, applications. I'm not advocating that you should always rewrite code, but sometimes re-use is relative to the constraints and requirements.

2007-12-31 13:42:07
Eric/Thanks for the comments. WSGI is not science fiction, and having the ability to use a product like black box of code is crazy.....crazy useful. If you want to see this science fiction working check out what the mad scientists at repoze are up to with Grok running in WSGI with Plone. One guy recently called a similar post, "full of crap", this is true, it is unbelievable! I am very excited about WSGI.

In regard to a previous post about Frameworks going away, I was being slightly artistic, in trying to say, that WSGI changes the whole paradigm. The framework is not center stage, WSGI is. They become less important day by day, but of course, never irrelevant.

Kevin Teague
2008-01-03 02:30:17
I'd disagree with the idea that it's troubling that everyone is writing wikis and blogs. People writing wikis and blogs in their framework of choice is a good thing. People need to "feed their inner hacker". Nathaniel Talbott did an awesome talk on the joys of hacking recently - where he writes a blog during this Why Camping Matters talk.

More pragmatically, while Plone 3 is a good blogging and wiki solution, it's not the good fit for all. If you've got a personal web site with a blog and wiki, Plone is often overkill, the $30+ monthly fee for a Plone hosting is pretty steep.

Also most of the exciting work in the Plone blogging space has been in creating aspect-oriented components that apply blogging features to ordinary content objects and lots of this work is still fairly young as this approach wasn't generally feasible until Plone 3. Unless you are well versed in the many layers of the Plone onion, it's not likely to be very satisfactory as a tool to "feed your innner hacker" as many people are doing in the hand-rolled blog-n-wiki space. ZCML is like escargo, a hacker food that causes many to make a "yuck" face when presented with as a dish.

Noah Gift
2008-01-03 03:12:23
Kevin/Thank you for your comments. That paragraph could have been phrased better. What I was trying to say is that if you want to learn how to write a wiki or a blog, then cool, go for it! I went down that road for a bit, but then realized that what I really cared about was focusing my energy on something that I couldn't just install like blogger or wordpress or Plone.

I am 100 % for people learning every nut and bolt of every technology on planet earth, including writing their own web frameworks just for the hell of it. My current focus in 2008 is to learn more about the innerworkings of Plone/WSGI/Grok as it is a nice set of technologies that share a common parent.

I would love to see people writing reusable applications and components that have not been written before, and that work across frameworks. This is partially because I am sysadmin at heart and want everything to work everywhere.

Here are some useful ideas for framework tutorials, although it would be really cool if they were WSGI middlewear that any framework could use:

1. How to build a reusable ecommerce solution that works in any framework and with any database.

2. How to manage unix utilities through the web.

3. A personal database like Filemaker pro.

2008-01-07 23:54:55
I agree with you:

I like python for its elegance and its
documentation which allows me to lookup
information at *one* place.

To compare Zope: ----
I would like to understand it better
(I already use plone and like it) but
on the documentation
is *scattered* like if a bomb has exploded.

... tons of (outdated or not, who knows)
tutorials, wiki ...

For me the documentation should be *the* manual
(like in python).
I zope the last manual as pdf is for 2.6
and for 2.7.
Wiki's blogs .. whatever should be optional.

2008-01-12 22:08:39
Documentation is crucial, in particular when a framework is hard to learn an unintuitive.
What about starting to make more intuitive frameworks like

Noah Gift
2008-01-14 17:29:48
Massimo/I tried out the OS X installer over the weekend for web2py. It is a great tool, with a built in development environment, that doesn't even require opening up a shell. I am also interested that you are developing this application in conjunction with a course you teach at the university. Keep up the good work! Also, you have great marketing and documentation.
2008-02-11 14:01:55
Thanks for this interesting article. A useful list of web application frameworks can be found at