[Twisted-Python] Updated defer.html

[Steve Waterbury]

"Clark C. Evans" wrote:
> 
> In fact, I had a complete mis-understanding of what Deferred
> was all about for quite some time, mostly a fault of that
> document for not having a runnable example.   

I agree the document needs improving to be useful 
to newbies.  The runnable examples in doc/examples are 
what saved me ... in fact, IMO the examples are way 
more important than the docs.  But I'd like to see more 
comments in them ... as Rob McCool says in the original 
mime.types file that came with NCSA httpd, 
"# This is a comment. I love comments."  :^)

> Documenting Deferreds suffers from a bootstrap problem; it is
> advantageous to introduce Deferreds before Threads, but to
> understand why you need Deferrerds you must already have
> read about Threads.   The typical solution to a bootstrap
> documentation problems is to iterate into a circle, introduce
> each concept and then after both concepts are glossed over
> going into more detail about each one.   An introduction
> to threads, and the Timer is the simplest threaded operation,
> is essential for motivating Deferreds...  

IMO, it doesn't take very much motivation ... I've never 
written a threaded program, and whereas it might be good 
for my soul, I'm not that eager to try it.  

> And, to be a bit
> defensive, you can't jump on my case here as examples later
> on use the Timer.

Now, now ... don't take it personally -- you're contributing 
something, which is more than I've done!  :^)  

I'm sure the later timer examples are fine, but I just 
didn't pay much attention to them as they weren't relevant 
to what I wanted to do with Twisted.  :^)

> | > perhaps it's overly jargonistic, but it is the way I think about Deferreds;
> | > they are the primary tool Twisted provides to abstract away blocking
> | > operations into a fundamentally asynchronous framework.
> |
> | Total agreement.  If they don't know what "asynchronous"
> | means, they can look it up!  Sheesh, it's a standard term.
> | (Twisted-specific jargon is not a problem in the docs
> | either, as it is always defined when introduced.)
> 
> Deferreds have *nothing* to do with deferring execution.  They are
> only an improvement/embellishment on the Python callback mechanism.
> That they are very useful in asynchronous contexts is nice, but
> that isn't what they do - they don't provide asychronous execution.

Yes, but Twisted *is* an asynchronous context; in Twisted 
that's what deferred's are used for.  :^)

> | > Again, with the next two examples I think you've obscured the point in your
> | > efforts to make everything explicit.  I'd rather have a 10 line example
> | > that illustrates a concept, than a 20 line example that obscures the same
> | > concept behind irrelevant method definitions, etc.  ...
> |
> | Agreed also.
> |
> | That said, I think there are cases where the in-line examples seem
> | a trifle too elliptical.  I'll have to be more specific, I know,
> | so I'll send an example when I have time.
> 
> Well, I disagree with both of you here.  You need *all* of
> the code so that a newbie doesn't have to fill-in the
> details, and get frustrated when they don't grok it.

Sounds like you agree with *me* at least:  
"elliptical:  of or relating to deliberate obscurity 
(as of literary or conversational style)" ... ;^)

Of course, I'm full of ideas, but you're actually contributing, 
so I'll shut up now ... just some suggestions from 
the peanut gallery ... carry on, Clark!  :^)  

Peace,
- Steve.