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.