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 _______________________________________________ Twisted-web mailing list [email protected] http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-web
