Dear Python, Why Are You So Ugly?

This reminds me of the jQuery docs situation. Every month or so somebody comes up with an alternative way to access them that's flashy and uses frames with low contrast text and lots of shadows and gradients. I play with the site for 60 seconds thinking "this is neat", and then go back to using the official docs because they come up in a Google search.

I don't think I've ever actually accessed the Python docs in any other way in fact. Same goes for Django. They're clean, static HTML, totally trivial for search engines to index and you always get just what you think you're getting when you click over from a search engine.

Also, unrelated: I learned something today. I read the claim that Python and Ruby are roughly the same age and thought "no way, Python is old-as-hell, Ruby can't be nearly as old". But then Wikipedia pointed out that Python is only 4 years older (1991 vs. 1995).

(Disclaimer: I'm the author of one of the books linked at the end of the post.)

Design is not just important for usability, but also for marketing. If you have an awesome framework, you have to get the word out so people know about it and want to use it. It's not the same kind of marketing a business uses because it's not directly tied to revenue, but it is important if you want said framework to be used and its surrounding community to grow.

How many blog posts do you see complaining about or even advocating the new framework hotness? People are jumping ship to Node.js now and saying Rails sucks, and there's consistently a new framework du jour. I'm not saying that's a good thing, but it is definitely proof that marketing affects framework adoption.

I know it sounds kind of scummy to talk about marketing OSS. The point isn't to position Python as the sexy new language everyone needs to switch to, but to represent the community and quality tools and knowledge it offers. If a new programmer visits the Django site and then the Rails site, might they assume Django is a smaller community because the site isn't as pretty? Maybe the first impression is that Django isn't as well maintained, when we all know that's not true.

> Really? In my experience, Django has about the best documentation of any open source web framework. How are the docs lacking?

It's been a few years so I don't recall exactly (and maybe it has improved) but I just found myself browsing and clicking around to re-read particular chapters all the time, that I could only reach via an unintuitive sequence of 2 or 3 clicks.

Only when I found that the docstrings inside Django's code, plus the function signatures and the (IMO very well-written) code itself, were much more useful--as long as you have an IDE that allows one to ctrl-click an identifier to jump to its definition (cross-file/module), only then I got a better grasp on what Django was doing and how it worked.

But then, that's the general take I got from Django after using it for some time: As long as you strictly stay within the "batteries included", it's absolutely great, and the documentation is probably wonderful and sufficient. But as soon as you need to develop your own `ImageFileWithMultipleSizesThumbnailAndExtraCheeseField`, you really need to dive into the innards of the code, the documentation starts lacking, and it's like they never even considered that sometimes your customers prefer their database fields with extra cheese.

Hey but I'm not here to bash Django, it's a great framework (and so is Rails, btw). It's just that next time when I need something like it, I'm going to try and use one of those WSGI things with SQLAlchemy and see how that works for me. I'll probably really miss the automatic admin though.

> I don't think I've ever actually accessed the Python docs in any other way in fact. Same goes for Django. They're clean, static HTML, totally trivial for search engines to index and you always get just what you think you're getting when you click over from a search engine.

I usually download them as local static HTML so I can also access them when I'm coding without stray wireless packets floating in the air.

Years ago when I was learning to code I chose Python over Ruby (and Java, etc) because of the aesthetics of the code. Python is so pleasing to look at on the screen.

I tend to agree with the premise of the article. I've thought the same for years.