[Twisted-Python] Evangelism notes...

[Stephen Waterbury]

Itamar Shtull-Trauring wrote:
> On Wed, 2005-05-04 at 16:08 -0400, Mike C. Fletcher wrote:
> 
> 
>>          o What do we call to shutdown the threadpool?  I don't
>>            remember, let's check the reference docs... 20 minutes of
>>            searching for the 2.0 reference docs (with the entire
>>            company watching this)... finally ask on IRC... told to
>>            build them myself and contribute them.  Cute, but didn't
>>            really drive home the whole "robust, professional,
>>            well-documented platform on which to develop business
>>            systems" meme as much as I'd hoped. 
> 
> 
> There's a problem with generating API docs with current release.
> Something to do with zope.interface. We did not decide not to build them
> just to annoy you.

Don't get too defensive, Itamar.  Although I missed the IRC
conversation, Mike's email certainly described a situation
that anyone would have found frustrating -- and to me it did
not appear to be an indictment of Twisted so much as simply a
cautionary tale, and a useful one.  It's reality.

Mike knows (in retrospect) he would have done things differently
if he had anticipated the docs not being there (i.e., go to his
cubicle and quietly do the spelunking, away from skeptical eyes).

I daresay if I were selling Twisted or handing off a Twisted
app in my environment, the situation would be similar (God
forbid I ever get to that ... which is part of the reason I
haven't released yet ;).

Twisted's documentation is constantly improving (thanks to Mary
and all who contribute!), but it can still be daunting to the
uninitiated, largely because Twisted is non-trivial and
good technical writing is harder than it looks.

Mike's experience was a confluence of many small dysfunctions.
IOW, the makings of a classic tragedy -- not that it was a
*huge* tragedy, but I'm sure Mike would prefer to work
in an environment in which he can use Twisted and not be
second-guessed (at best), and as he ruefully points out, the
well is kind of poisoned now.

So what's to be learned?  The lesson for me is:  if you are in
a similar environment, go ahead and used Twisted -- to those who
know it, it is reasonably robust and scalable -- but be very,
very careful when demoing and/or introducing anyone else to your
app.  And if you encounter any bugs, no matter how insignificant
the might at first appear, for heaven's sake go back to your
cube for the spelunking, unless you are a Minion and know
exactly what you're doing!  ;)

Cheers,
Steve