On Tue, Feb 25, 2003 at 05:18:04PM -0500, Jp Calderone wrote: | This isn't entirely fair. TAPs may be completely irrelevant to you, if | you're only developing with Twisted.web, but documentation about them and | all the other features of Twisted doesn't mean Twisted's documentation | "isn't very good" - it just means Twisted does more than you care about.
I think it is entirely fair critique. And I don't think it is disparaging... no software project is ever perfect. Webware and Twisted are among the most innovative and best run projects out there... despite their documentation. ;) The context of people on _this_ list (and probably 90% of the visitors to the twistedmatrix site) is mostly building app servers, and from that context the Twisted documentation is quite hard to grok -- I'd bet that many potential users don't get past what I took as the "start here" page: http://www.twistedmatrix.com/documents/howto/using-twistedweb This page dives right into taps in their gory details. It left me totally confused for quite some time, enough to where I discarded the on-line documentation entirely. I'm clearly not alone here... http://www.twistedmatrix.com/pipermail/twisted-python/2003-February/002792.html This thread goes on-and-on in a "defense" of taps without ever answering the poor fella's question... how to get started. Luckly, another person who asked the question a second time got a very clear and succinct answer: http://www.twistedmatrix.com/pipermail/twisted-python/2003-February/002940.html To "fix" the documentation, this example should be used as the starting point, with additional pages dedicated to adding "features" to the handler, such as threads, error-handling, reloading modules, sessions, authentication, persistence, etc. Then, as the example gets more and more complicated, then, (and only then?) does it make sense to introduce TAPs to explain how these complexities can be immensely simplified. In fact, *all* of my understanding of twisted came not from the on-line documentation but from the very helpful mailing list... quite clearly Twisted has some serious talent in the community (you included) and I really look forward to learning more... gradually. | I mean no slight to Webware, only to point out that Twisted and Webware | aren't aimed at the same target. First, I don't think you can easily "segment" these two projects that way, IMHO, they are mostly in direct competition with each other. Both provide for servlets, database pooling, authentication, and numerous other add-ons. Webware even has the idea of handling multiple protocols, although that hasn't been further developed. And yes, the breadth of both projects is their achilles heal. They each have a great many add-ons which can and should be managed as separate sub-projects; complete with their own owner (as distinct from the owner of twistedmatrix.com), their own domain, like taps.twistedmatrix.com and its own documentation. Mixing all of these items together has three affects. First, it is very daunting for the newbie (too much information). Second, it has a tendency to create unnecessary technology dependencies. Third, and perhaps most problematic, it eliminates competition for building perhaps competing sub-modules. The apache webserver does very well here and has dominated not beacuse of the core technologies, but beacuse of the modules which have been developed around it. Too many people have this "fear" of competition. So what if Twisted and Webware are in direct competition. That's good... I hope these two projects "steal" alot from each other. Clark ------------------------------------------------------- This SF.net email is sponsored by: Scholarships for Techies! Can't afford IT training? All 2003 ictp students receive scholarships. Get hands-on training in Microsoft, Cisco, Sun, Linux/UNIX, and more. www.ictp.com/training/sourceforge.asp _______________________________________________ Webware-discuss mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/webware-discuss
