I'm sorry you don't like zope.interface. Do you prefer ABCs? What would make interfaces better for you? Did you prefer Twisted's builtin interfaces to zope.interface?
How was the community unfriendly? What can we do to improve the community experience?
(Anecdote: The only way I've been productive with Django is through reading their source; their IRC channel and documentation are useless.)
2. Make it short. As short as you can possibly make it and still have it be a good tutorial. If someone has to spend 3 hours reading docs before they can even begin to start writing something, they're just going to go off and use some other framework. For example, the "introduction" section consists of three pages [2][3][4] that should all be cut. They're either fluff that no one except the developers are interested in reading, or provide information that is way too advanced for a newcomer to understand.
3. Throw away the finger tutorial. Completely. It's about 5 times longer than it should be. It also makes the old mistake of "here's how to do it, no turns out that's the wrong way, here's the right way, no turns out THAT was the wrong way, HERE's the right way". You need a tutorial that's short, and that addresses the most common use-cases for your product. This will probably involve a TCP server or an HTTP server.
4. Make sure that after reading your tutorial and nothing else, someone could actually go build a small project, organized in the correct style. That means they're going to have to know about twistd, services, factories, protocols, reactors, zope interfaces, and more.
5. If it seems like fulfilling #4 is going to be impossible, then there's a problem with the design of the system, i.e. it's too complex, and needs to hide more of its implementation details from the user.
6. Pages like these [5][6] are going to scare most of your users away. They seem to exemplify the worst of the Enterprise Java interface-for-a-factory-of-factories code bloat that most web developers live in fear of. If this is really the "right way" to develop Twisted apps, then that needs to be explained sooner, and more concisely.
7. Look at your competition! The documentation for Node.js is sparse (a little too sparse) but it's not bad. Check out their synopsis page [7] (useful!). The entire API docs are fairly well-commented, have lots of examples, and (and this is important) never nest more than one level. The front page is itself the minimum viable documentation. If they had a couple extra pages on how to use modules correctly and how to run a node as a system service and it would be doing pretty great.
8. My issue with Twisted's use of interfaces is that it makes the API documentation really hard to read. Every function or class I want to use requires an ISomething that I've never heard of and don't know how to create. Then it turns out that my service or factory or whatever actually is an ISomething, but I didn't know that because the thing that created it returns an ISomethingElse BUT because I asked for it to be a TCP server it's actually an instance of SomeClass, which also happens to implement ISomething. Which I only find out by asking in the IRC channel.
9. In my experience, asking questions in the IRC channel makes you feel stupid. The people there tend to give off the feeling of "oh god, this is so simple, why don't you know that to start a Foo you need to pass it an IBar, which your particular service counts as because ..., DUH". Maybe the IRC channel is not supposed to be for support, in which case...you need better documentation :p
Good luck! Documentation writers are the unsung heroes of many a project, forging success and popularity with little recognition. Twisted also has a lot of cool features that Node does not; I would be happy to see them succeed.
[1] http://twistedmatrix.com/trac/wiki/Documentation
[2] http://twistedmatrix.com/documents/current/core/howto/vision...
[3] http://twistedmatrix.com/documents/current/core/howto/overvi...
[4] http://twistedmatrix.com/documents/current/core/howto/intern...
[5] http://twistedmatrix.com/documents/current/core/howto/tutori...
[6] http://twistedmatrix.com/documents/current/core/howto/tutori...
