Ryan Tomayko

Writing good documentation —

Jacob Kaplan-Moss:

It’s really tempting to use an auto-documentation tool like Javadoc or RDoc for reference material.

Don’t.

Auto-generated documentation is almost worthless. At best it’s a slightly improved version of simply browsing through the source, but most of the time it’s easier just to read the source than to navigate the bullshit that these autodoc tools produce. About the only thing auto-generated documentation is good for is filling printed pages when contracts dictate delivery of a certain number of pages of documentation. I feel a particularly deep form of rage every time I click on a “documentation” link and see auto-generated documentation.

Hate that shit.

You know what I want? Man pages. For everything. Wouldn’t it be cool if you didn’t have to write roff?

Toward a new self-definition for open source —

Ian Bicking’s talk from DjangoCon 2009. Stimulating. I’m sure a nice comment thread will develop here over the next few days as well.

Snakes on the Web —

Jacob Kaplan-Moss somehow pulls a bunch of interesting contemporary web development issues into a coherent essay. This bit on what happens when web apps begin to mature is especially well stated:

This is an impossible situation for framework developers: by optimizing for a quick start, by focusing on common needs, we’re essentially guaranteeing future failure. Remember the “Rails doesn’t scale” pseudo-controversy last year? I guarantee it’s only a matter of time until there’s an angry “Django FAIL” moment.

Frameworks ought to gracefully fade away as you replace them, bit by bit, with domain-specific code. (This is what I meant, above, that inter-op is also a scaling issue.) Right now, they don’t.

I wish more people would write about their experiences growing out of the general purpose web framework. It’s a totally natural thing but most people seem hesitant to talk about it because it’s interpreted as an attack on the framework or community.

Dropping Django —

This seems to be a trend in Python and Ruby web circles. Frameworks present developers with a choice: accept these constraints, give up a little control, and I’ll make you more productive. Longer-lived apps start to evolve out of the framework at some point, though. You need more control over a piece here, or aren’t satisfied with the way something works there, and so you refactor and pull stuff out until the framework begins to slowly fade away. Maturity is a part of the web app development lifecycle we have precious little data on.

This comment nails it:

Maybe it worked out exactly like it should have. Django bootstrapped your app to a certain point. Got you further faster than you would have if you implemented everything from scratch. Then from there, you identified the things you considered inadequate and replaced them. If it all goes away who cares. You have learned something, shared it with us and moved on.

I think that’s just fine. Unexpected maybe, but fine.

djng—a Django powered microframework —

Simon Willison is working on python web microframework based on Django. This will get interesting. Fast.

ETags And Modification Times In Django —

Nice look at caching idioms in Django and why you need to generate HTTP cache validators up-front and efficiently.

Django’s cache framework —

All frameworks should approach caching the way Django does. The core app/origin framework does no real caching but provides utility/helper methods for setting standard RFC 2616 cache related headers on the response easily and correctly. A completely separate set of caching goo (“middleware”) sits between your app and performs the actual caching based purely on the headers set by the origin. The benefit to this approach is that caching is totally independent from the app framework and can be swapped out for a true gateway (“reverse proxy”) cache at any time.

Google App Engine —

Christmas in Python land! Run Python/WSGI code on Google’s infrastructure. This is an incredibly H U G E win for the Python web community and further validates WSGI’s architectural awesomeness.

I Can Haz Hardcore Forking Action —

More praise for GitHub from a small team of Django hackers that built a site in three hours on one night with a little help from git…

Django People —

Simon Willison’s latest project makes it easy for people developing in Django to hook up and get laid (since they have so much free-time due to developing in Django).

What PHP Deployment Gets Right —

Ian takes a look at some of the attributes of PHP’s deployment model, why they work so well (for PHP), and why other environments have such a hard time duplicating them.

10 Reasons Why Django kicks Ruby on Rails’ collective ass. —

Wherein the author lists 8 reasons (maybe 3 of which are approaching objective or even valid) and also spells Adrian’s name wrong: “Adrian Zolovaty”. Ruby/Python flame-bait is exactly what we need.

A fundamental way newspaper sites need to change —

Outstanding piece. Adrian ought to write more often. Microformats.org could really use someone with Adrian’s background to squash some of the “why?” type questions.