Frameworks, Documentation and the Joy of Django
jws
http://www.jrandolph.com/blog/?p=45 regarding evaluating frameworks,
I'd like to make an observation.
Within the Python web framework ecosystem(and I mean for ecosystem to
imply a mind-bendingly complex system of interconnected parts) we don't
really 'get' the success of Rails. Without resorting to advocacy, I
think it's fair to say that the general perception is that RoR seems to
receive praise far out of proportion to it's technical merit. Sure,
it's good, but it's not ten times as good. From where we stand, it's
interesting, but hardly a radical improvement. We have comparable
technology in most common cases.
Given the recent security problems with Rails, it's clear that the RoR
community is not infallible. Why have they then received so much praise
and admiration? It's not the technology, it's the narrative.
It really doesn't matter if the framework is single-source(Django) or
best-of-breed(TurboGears). What matters is a unified, contiguous
narrative story. A tutorial does not branch("if you're using SqlObject
then abc, but if you use SQL Alchemy, xyz instead"). If you force the
reader to make a decision, you have strayed far from the path of
wisdom.
The Rails community hit this one out of the park with their
screencasts. When evaluating frameworks, you want to get a feel for how
it works in broad terms. This is not the same as 'well-documented'.
Documentation tells you how product features work, a narrative tells
you how use the product. A tutorial should never tell me to refer to
the documentation of another project. Zope is well-documented, but try
explaining it to someone who's never used it before. Likewise, A wiki
is great for reference material, but it's no replacement for a
step-by-step walkthrough of actually doing work in the product. The
point is not that you can create a blog or wiki in 15 minutes,
It's that you can understand _how_ to_ in 15 minutes!
This relates to Django because the tutorials are better here than any
other Python framework I've seen. By pointing this out as a strength, I
hope we keep and grow this as we approach a 1.0 release. Note that this
has nothing to do with the technology and everything to do with the
good judgment of the core dev group. Go team!
(I do, however find it weird that anytime someone posts anything about
Django anywhere in the world, the first comment is always by Adrian.
It's kind of freaking me out.)
David Larlet
>
[snip]
>
> Given the recent security problems with Rails, it's clear that the RoR
> community is not infallible. Why have they then received so much praise
> and admiration? It's not the technology, it's the narrative.
37signals is the best Buzz2.0 company you know :-).
>
> The Rails community hit this one out of the park with their
> screencasts. When evaluating frameworks, you want to get a feel for how
> it works in broad terms. This is not the same as 'well-documented'.
> Documentation tells you how product features work, a narrative tells
> you how use the product. A tutorial should never tell me to refer to
> the documentation of another project. Zope is well-documented, but try
> explaining it to someone who's never used it before. Likewise, A wiki
> is great for reference material, but it's no replacement for a
> step-by-step walkthrough of actually doing work in the product. The
> point is not that you can create a blog or wiki in 15 minutes,
>
> It's that you can understand _how_ to_ in 15 minutes!
Just a testimony, I have to learn symfony php framework (django rox
but my boss no...) recently and I'm really surprised by the quality of
the documentation. Have a look at:
http://www.symfony-project.com/content/documentation.html
It's really clear: you have tutorials on the top and documentation at
the bottom. I think it's interesting to have two kind of tutorials for
Django too:
* a quick one for a first overview.
* a second one for a real site, everybody knows that a real site can't
be done in 15 minutes!
For the moment, polls app is great but not as fast as "create a blog
in 5 minutes" (and with generic views it's possible to do that). In
this case, the user doesn't understand exactly what happens but he is
really impressed and want to know more about this wonderful framework.
Next step is the real site one which explain exactly what happens and
Django mechanisms. This one can be detailed and follow a kind of time
line to reflect the "reality" of the tutorial.
Just my 0.2cts
David