Launching Multiple Servers

[Andrew Bennetts]

On Thu, May 22, 2003 at 08:45:29AM -0400, Peter Hansen wrote:
> Andrew Bennetts wrote:
> > 
> > Twisted isn't so much complex as *large*.  The trick is knowing which bits
> > matter to you, and which parts to ignore -- unfortunately, or docs are
> > fairly mediocre at helping you with that :(
> 
> I don't entirely agree.  Yes, Twisted is large, but there isn't really
> any trick needed.  Just read the necessary How-Tos (such as on how to
> make a simple TCP server) and (with a basic background in sockets) you 
> should have a working basic multiple-server app within a half hour or
> less.  Heck, just use the example code and run it: it works.
> 
> There's no reason to worry about the size of Twisted, or figure out
> "what to ignore".  There's an incredible amount to Twisted (I assume)
> beyond what I've used so far, but that fact has not in any way 
> inhibited my work as Twisted is so well structured.
> 
> Maybe I'm weird: I even found the docs to be pretty good.

We get mixed feedback.  Some people do seem to get overwhelmed by the
breadth of Twisted, and have trouble finding what they need to know.  Other
people, like yourself, seem to manage just fine.  

This is mainly conjecture on my part, but as far as I can tell, the main
reason why some people have trouble is they can't narrow down the docs and
examples to what matters most to them.  We have a fairly large amount of
terminology, which can leave people wondering "What the hell is 'reactor',
'factory', 'woven', 'spread', 'pb', 'TAP', 'Deferred'..." (which is why I
wrote the glossary).

Our docs aren't structured in such a way that you can say "I want to find
out how to implement a new protocol" or "I want to deploy a Twisted Web
server", and immediately know which How-Tos are relevant to you.  And the
example code is very poorly categorised, and in places could do with more
comments describing what they demonstrate.

Despite all that, the docs at least fairly comprehenisive now[1] (over 250
pages as a PDF!), and they do seem to be enough for at least some people.
I'd think I'd rate them as "ok" rather than "pretty good"; but I think it's
healthy for developers to be a little harsh about their own work <wink>.

-Andrew.

[1] When I started using Twisted, I had to learn pretty much everything by
    asking on IRC; even the "Writing Servers" document didn't exist.  Of
    course, that might be because I'm unusually thick rather than because
    the docs were unusually sparse... :)