[Twisted-web] Thoughts on documentation, wading into Twisted, Nevow, etc.

[Duncan McGreggor]

Terry Jones wrote:
> Here's a summary of thoughts I've had over the last month or so. Please try
> to take the following as positive / constructive.
Terry, that was a great email. Thanks for the time and consideration.

I'd have to say that I agree with you almost entirely. I tend to run
into two different types of responses when I talk to people about
developing in Twisted (with regard to the documentation):

1) what they hell? how can you possibly use this? I don't understand
what the hell they're talking about! and

2) wow! this is SO much better than what it used to be -- I think I can
actually use twisted now.

I have been using Nevow since it was first made "public" at pycon 2004.
It's the best thing out there for web dev that fits my brain. However, I
have had a very difficult time getting dev shops to adopt it.

Yet, I have had a few wins lately -- because of several fully developed
applications I built for different projects. They were amazed at the
applications' architectures, soundness, etc. -- all thanks to the
relative logic and soundness of Twisted/Nevow and its developers. Living
examples that demonstrate "best practices" may be one of the biggest
lacks in the Nevow docs right now. This has come up several times on
IRC, as well.

What the developers in those shops were able to see for the first time was:
* how python classes were used to construct sections of a site (using
rend.Page)
* how python classes were used to construct sections of a page (using
rend.Fragment)
* how slots are created and filled
* the usefulness of data_*() and render_*() methods
* the manipulation of sequences in the XHTML templates

Once the developers in the shops saw the whole picture with clear, clean
code that did exactly what you would expect it to do, they were sold.
They can't wait to do the next few projects using Nevow (instead of
Plone). I haven't seen these guys this excited in a long time.

It seems there is a need for several tutorials/documentation updates to
fill these needs. One of the greatest strengths of Nevow, though, is its
flexibility. The combination of Twisted and Nevow almost provide more of
a "meta web dev framework" than one of the "competing" web frameworks.
And this naturally makes documentation of "the right way to do it"
rather difficult. One solution may be a series of tutorials addressing
various needs/circumstances while outlining the benefits/reasons for the
given approach.

I've been thinking of writing a new tutorial lately. Maybe we should
crank a few out... hmm, on that thought, maybe there should be a
standard format for Nevow tutorials. "Intended Audience", "What this
tutorial addresses", "What this tutorial doesn't address", "Components
used", etc. Dunno. Just rambling now. Glad you're writing about this :-)

d