[Twisted-Python] Docs for twisted

[Ken Whitesell]

Three thoughts come to mind - coming from someone who has climbed 
the Twisted learning curve for the last year.

1) The docs I'd like to see would be of a more tutorial nature - it 
would seem to me that they would be the easiest way to reach a 
"lights on" stage. The sample code is good - and the finger tutorial 
is fine (for what it addresses) - but there are still lots of bits & 
pieces that seem to be hidden.

At some point, you reach the "Ah-ha!" stage. The learning curve 
greatly flattens out at that point. (At least that was my personal 
experience with Twisted-PB.) Once you reach that point, everything 
else becomes much easier to learn.

It helps a _whole_ lot to have a specific project / task in mind. 
Part of this is understanding your task sufficiently well to be able 
to divide it into the components as they apply to Twisted, and build 
carefully, step-by-step. (In my case, I built a multi-room chat 
server. Not a whole lot of code, but takes advantage of a number of 
different principles.)

I think it also helps, as painful as it may seem, to force yourself 
to work through the tutorials in the book by typing the code rather 
than just reading it. There's a more intimate association that you 
develop by going through the actual process than just running the 
existing code.

2) A current road map may help. I've seen various comments about 
modules being "not-quite-primetime" or "an old way of doing things" 
(specifically, I'm thinking about Enterprise, other than adbapi, and 
TAC / TAP files) Yes, Python (and Twisted) is the "Batteries 
Included" environment, but as someone pointed out to me at PyCon, 
some of those batteries are dead. I'd really like to know what 
modules I should avoid.

3) Even something like a directed HOWTO could be incredibly useful.
For example:

If you want to build a web server - read Chapter 7, Web 
Applications, section 7.1 and look at sample "xxx" - where sample 
"xxx" is the simplest and most straight forward first example of a 
web server.

There's a _lot_ there, and wading through it can be frustrating. The 
only way I managed it, was to print out the consolidated HOWTOs in 
the book.pdf file and read Chapter 6 repeatedly. After about the 
10th repetition, along with working through the samples, things just 
started falling into place.