Hear! Hear! My major disappointment with Twisted is its documentation. I've used many many packages over the years, some with books and books of documentation (HP OpenView, e.g.), but I've never encountered a package with poorer help for a newbie.
I finally started to get it when I stumbled upon http://krondo.com/blog/?page_id=1327. This has to be one of the best tutorials I've seen on any topic. It should be the *first* link in any Twisted tutorial, IMO. Vic On Thu, Jan 20, 2011 at 8:57 AM, Jason Rennie <jren...@gmail.com> wrote: > On Thu, Jan 20, 2011 at 2:55 AM, Glyph Lefkowitz > <gl...@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/ > > > _______________________________________________ > Twisted-Python mailing list > Twisted-Python@twistedmatrix.com > http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python > > -- “A designer knows he has achieved perfection not when there is nothing left to add, but when there is nothing left to take away.” -- Antoine de Saint Exupéry
_______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
