[Twisted-Python] Re: Teach Me Twisted Redux

Drew Smathers drew.smathers at gmail.com
Thu Mar 20 14:21:00 EDT 2008

On Thu, Mar 20, 2008 at 11: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 think "abysmal" is really an overstatement. A lot of external
documentation for Twisted exists
- though some of it is indeed too esoteric for the casual beginner.
The twisted team realizes this and they are improving the
documentation and setting high standards for documenting new additions
to the library - take the initial doc string for amp as an example.

>  (yet this same group complains that Git is too complex to be used for
>  source code control... even though its core architecture eclipses the
>  alternatives being used and considered...)

Tangential, but I know of at least two Twisted developers who are
using Git.  The evaluation of version control tools usually includes
whether or not the tool works across platforms well - Git does not
eclipse the alternatives in this category.

>  For example, I've been playing with Twisted for a while now and only
>  recently stumbled upon AMP... perhaps thats a personal issue and I do
>  have fundamental intelligence limitations... but perhaps its
>  illustrative.

Agreed, AMP needs some external documentation alongside PB in the main
documentation page.  Maybe I'll contribute a document myself - unless
someone else is already working on such? -, since I find myself using
amp a lot these days.  There are instances when you want access to
remote objects where PB (or the newer foolscap) are great for - but
for functional command-dispatch based RPC, amp really shines.

>  What we need is a core documentation / presentation / communication
>  strategy to communicate what twisted is and a vehicle to support
>  education.  Handling conferences is a degenerate case which requires
>  extension with malt beverages.

Which takes time (writing good documentation is arguably harder than
writing good code) - and community support.  And time is money ... so
contribute to Twisted so they can hire more documentation experts :-)

\\\\/ // //\/\\\\\\\
\\\/ \\// /\ \/\\\\
\\/ /\/ / /\/ /\ \\\
\/ / /\/ /\ /\\\ \\
/ /\\\ /\\\ \\\\\/\

More information about the Twisted-Python mailing list