[Twisted-Python] Refactoring Documentation

[Jason Rennie]

On Thu, Jan 20, 2011 at 2:55 AM, Glyph Lefkowitz <glyph at twistedmatrix.com>wrote:

> (minor nitpick: I really like "event-based" or "event-driven", as you've
> said here: why does <http://docs.recursivedream.com/twisted/> say
> "asynchronous"? I find that especially in documentation it's a lot easier to
> explain "event-driven", because you can enumerate what the events are,
> instead of explaining the etymology of "synchronicity"...)
>

I was also surprised by the choice of "asynchronous".  From wikipedia:

In programming, asynchronous events are those occurring independently of the
> main program flow. Asynchronous actions are actions executed in a
> non-blocking scheme, allowing the main program flow to continue processing.


My understanding is that this is the opposite of what twisted is.  The
reactor hands-off control and must wait until control is relinquished.  It
handles events when it checks for them, not necessarily when they happen.
 The reactor and application code blocks, possibly halting the entire
application if it is not written cooperatively.

This was a major point of confusion for me when I started to use twisted.  I
see that if I had carefully read the first few sentences under "Reactor
Basics" in
http://twistedmatrix.com/documents/current/core/howto/reactor-basics.html, I
might not have been so confused.  But, this is one of about 50 links on the
"core" documentation page, which is one of about 20 links on the main
documentation page.  I'm guessing that simply editing and reorganizing
existing documentation would go a long way toward fixing the documentation
problem.

Personally, I'd love to see documentation organization that mimics Python's,
especially the Tutorial/Library Reference/Language Reference breakdown.
 Users tend to know the level of understanding they are looking for and
Python's documentation reflects that.

Cheers,

Jason

-- 
Jason Rennie
Research Scientist, ITA Software
617-714-2645
http://www.itasoftware.com/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20110120/ea0b3616/attachment.html>