[Twisted-web] Re: Thoughts on documentation, wading into Twisted, Nevow, etc.

[Cory Dodt]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

L. Daniel Burr wrote:
> On Fri, 07 Jul 2006 07:10:51 -0500, Valentino Volonghi aka Dialtone
> 
> I think that worrying about attracting an audience that prefers to use the
> thread-based approach is doomed to failure, in the same way that inviting
> a conservative to adopt liberal ideals is doomed to failure.

Well said.  Let's focus on the positives of Twisted, not the negatives of
threading.  The ones I always come back to are integrating multiple protocols
and absurdly easy development of new protocols.  The big cloud of utilities
like t.py.usage, the service framework, etc. are also big plusses.

Stuff like 'better than threads' and 'integrates with all these gui toolkits'
are not so much evangelism features as they are *reactions to objections to
Twisted*.  Specifically, they are reactions objections that "threading is
easier" and "but I can't use Twisted with GTK/qt/...".  We need to document
those things, but if your goal in writing documentation is to get the reader
hooked early on, put the other stuff first.


> I don't think this would help much either, in that people who like to
> use threads most definitely do *not* see them as being harder to use
> than the twisted approach; on the contrary, they find threads to be far
> more natural to their way of thinking, and most of them have never run
> into the kinds of serious problems that threading can introduce.  I
> sincerely believe that until a person actually encounters a serious
> thread-related problem, they cannot be convinced to adopt anything that
> does what twisted does.

I can actually quibble with this notion from personal experience: I used
Twisted before I did more than very trivial experiments with threading.  I
read and understood in concept the problems with threading.  Only later on,
when I tried to use threads in my Twisted programs did I encounter the hazards
of threading.

This is important because it anecdotally demonstrates that programmers don't
always go straight to threads.  If they understand from the start that
concurrency is going to be hard, they will be (as I was) suspicious of what
threads do, and might (as I did) seek experts who've done this stuff before.

I don't think we can control who goes to threads and who goes to the
asynchronous model, but there will be some of each.

> I have to agree here.  I have used twisted since the 0.9 days, and I have
> always found the documentation to be perfectly adequate.  Honestly, while
> I recognize that the vast majority of interested parties find the docs to
> be incomplete or confusing, I have never had the problem, and so I am
> struggling somewhat in understanding how to solve it.

I think I understand the problem.  The problem is that concurrency is hard.
If you're a new programmer, and you want to start with "a simple network game"
(because somebody told you not to start with Doom), you're going to discover
all kinds of complexity that your brain isn't formatted to handle.

And Twisted's documentation doesn't do that for you.  It assumes that you
understand that new programmers should start with a simple *text processor*,
not a simple network game, then work up to a simple clone of nibbles, then
maybe give a personal IRC bot a try, then ...

It assumes, in short, that you've already done all that, and you're ready to
write a real application at this level.  Should it mention that that other
ground must be covered first or you'll be unhappy with the results?  It could.
Should it cover all that ground for you?  No way.

It's not about how smart you are, it's about whether you have the relevant
experience to write an application that actually needs Twisted.  I think
anyone who actually has the experience necessary to tackle an application with
concurrency is going to find the doc a lot more friendly than someone who
doesn't.  I don't know that that's Twisted's fault.



> Perhaps the problem is that the twisted docs primarily teach the theory
> of operation (Deferreds, Protocols, etc.).  For someone like myself, the
> theory of operation is exactly what I want to know.  For others, I suspect
> there is more value in documentation that covers things of a very specific
> nature, such as "how to build a web application that talks to a database",
> or "how to build a DNS server", or other such use-case-oriented fare.
> ...
> So, maybe a "Build a real, working, application in 15 minutes" is the
> kind of fare needed to make twisted more palatable to the audience that
> is currently being frustrated in achieving twisted zen.
>

Totally agree here, but I still think someone who is ready to "build a web
application that talks to a database" is going to understand the walkthrough a
lot better than someone who isn't.  (I thought the finger tutorial actually
covered that, but I guess it doesn't on quick skim-through.)


Just a final thought: there's still lots of areas that *aren't* adequately
documented by anyone's standards.  There are areas not covered by examples,
there are areas not covered by HOWTO's.  The core is covered, but any new
application worth writing probably uses stuff from the fringes.  So our
hypothetical new Twisted user starts out writing her new application, gets a
handle on the core stuff, and then discovers those gaps in the fringes.  That
can be frustrating.  Everyone uses a different part of the fringes, so the
fringes need to be covered almost as well as the core.

C

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2 (MingW32)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFErq5t3A5SrXAiHQcRAkUEAJ9nvBkTSq1/M43lm+XWTmlbfUdVDgCeMfUs
4QQgyJYHgK1qVpD1zPosEtA=
=A5qF
-----END PGP SIGNATURE-----