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:
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...
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:
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
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.