[Twisted-Python] Re: In Defense of Taps

[Moshe Zadka]

On Wed, 12 Feb 2003, Glyph Lefkowitz <glyph at twistedmatrix.com> wrote:

>  1. Not very many mature projects use Twisted yet.
>  2. Everybody hates TAPs unless I've personally explained why they shouldn't.

We should at least take those results as far as our single best opportunity
to do advocation: PyCon in general, and Itamar's tutorial in particular.
I think we all believe that (at the very least) twisted.internet is ready
for production-code. We all believe that TAPs are useful. I think we should
take the opportunity in all talks to emphasise how useful these things are.
Again, this seems mostly relevant for the introduction talk: I understand
how tempting it is to skip writing plugins in the introduction, but this
shows that it shouldn't be (because writing plugins for tap *is* easy).

Also, I'd attempt to take another conclusion from it: people used to complain
Twisted is not documented enough, but I think now the complaint is that
people are not sure where to start from. Part of it is a real problem:
the skills a Woven developer should have are (almost) complete disjoint
than the skills a programmer imlpementing a new kind of server (say,
SFS): the first would just use a quick mktap web --path/twisted-web
package to set up the server, and start writing .rpy's, while the
later would spend most of his time minding the protocol, and only ending
with writing an mktap plugin. What is my conclusion? I consider only
the second programmer "primary Twisted audience": not specifically web
programmers, but network programmers. For network programmers, the following
HOWTOs are useful:

* servers
* plugins
* cred
* pb-cred
(I think this is a decent order of reading them).

It would be nice if we could make special indexes for special kinds
of programmers, pointing them to a specific reading of the documentation.
How to do it is left as an exercise to the reader (but I will note that
on the TeX side, we're pretty much covered so it really more of a question
of decisions than of technology).
 
I encourage the "newbies" on the list to speak up: what are *you* planning
to do with Twisted, and which documents would help you with that.

-- 
Moshe Zadka -- http://moshez.org/
Buffy: I don't like you hanging out with someone that... short.
Riley: Yeah, a lot of young people nowadays are experimenting with shortness.