[Twisted-Python] Re: Teach Me Twisted Redux

[Brian Granger]

On Thu, Mar 20, 2008 at 9:36 AM, Glenn H Tarbox, PhD <glenn at tarbox.org> wrote:
>
>
>  On Thu, 2008-03-20 at 07:33 -0400, Steve Holden wrote:
>
> > glyph at divmod.com wrote:
>  > As I believe I mentioned early on, one of the issues is that the Twisted
>  > core developers are so smart (I believe I may have used the phrase
>  > "brains the size of planets"), and so knowledgeable about Twisted, that
>  > it's difficult sometimes to get a 90% answer out of them. This was
>  > particularly the case with Itamar, whom I lambasted quite mercilessly
>  > (and whom I therefore owe a public apology: sorry, Itamar) when he tried
>  > to complete all the corner cases after a slightly inaccurate statement
>  > on my part that was perfectly good enough for a learner.
>
>  There is a great deal of anecdotal evidence that great players make poor
>  coaches.
>
>  One of the biggest (glaring?) issues with Twisted is the abysmal state
>  of the documentation (none) making the code the best source... and
>  history is replete with the massive successes that approach has borne...

I disagree with this evaluation.  While parts of Twisted could be
better documented, overall, it is pretty darn good for an open source
project that addresses a problem as difficult as asynchronous
networking.  How many open source projects have a book?

>  What documentation there is includes: "If you need to call a method that
>  returns a deferred within your callback chain, just return that
>  deferred, and the result of the secondary deferred's processing chain
>  will become the result that gets passed to the next callback of the
>  primary deferreds processing chain"
>
>  Now, the above is true and clear to those of us who know twisted... but
>  I've used that quote for levity... its simply incomprehensible... but
>  absolutely critical to understanding the power of twisted.  I'd say that
>  the current state of twisted documentation is in part represented by
>  that quote... and much of the reason twisted gets thrown out early as an
>  option.

Asynchronous networking is simply hard.  And Twisted has a very
sophisticated take on it.  Saying the problem is the documentation is
like someone saying "quantum mechanics is poorly documented...all that
talk about Hilbert spaces, eigenstates and superposition..."  It is
not poorly documented, it is simply hard and conceptually challenging.

Also, I think the proof is in the pudding.  Most people who really
need Twisted for their projects _are_ in fact able to learn it (for
the most part without reading the source code).  The documentation
can't be that bad.  Doesn't mean there is not room for improvement
though.


Brian