Hear! Hear! <br><br>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.<br>
<br>I finally started to get it when I stumbled upon <a href="http://krondo.com/blog/?page_id=1327">http://krondo.com/blog/?page_id=1327</a>. 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.<br>
<br>Vic<br><br><div class="gmail_quote">On Thu, Jan 20, 2011 at 8:57 AM, Jason Rennie <span dir="ltr"><<a href="mailto:jrennie@gmail.com">jrennie@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
<div class="gmail_quote"><div class="im">On Thu, Jan 20, 2011 at 2:55 AM, Glyph Lefkowitz <span dir="ltr"><<a href="mailto:glyph@twistedmatrix.com" target="_blank">glyph@twistedmatrix.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
<div style="word-wrap: break-word;"><div>(minor nitpick: I really like "event-based" or "event-driven", as you've said here: why does <<a href="http://docs.recursivedream.com/twisted/" target="_blank">http://docs.recursivedream.com/twisted/</a>> 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"...)</div>
</div></blockquote><div><br></div></div><div>I was also surprised by the choice of "asynchronous". From wikipedia:</div><div><br></div><blockquote class="gmail_quote" style="margin: 0px 0px 0px 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
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.</blockquote>
</div><div class="gmail_quote"><div><br></div><div>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.</div>
<div><br></div><div>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 <a href="http://twistedmatrix.com/documents/current/core/howto/reactor-basics.html" target="_blank">http://twistedmatrix.com/documents/current/core/howto/reactor-basics.html</a>, 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.</div>
<div><br></div><div>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.</div>
<div><br></div><div>Cheers,</div><div><br></div><div>Jason</div><div><br></div><div>-- </div></div>Jason Rennie<font color="#888888"><br>Research Scientist, ITA Software<br>617-714-2645<br><a href="http://www.itasoftware.com/" target="_blank">http://www.itasoftware.com/</a><br>
<br>
</font><br>_______________________________________________<br>
Twisted-Python mailing list<br>
<a href="mailto:Twisted-Python@twistedmatrix.com">Twisted-Python@twistedmatrix.com</a><br>
<a href="http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python" target="_blank">http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python</a><br>
<br></blockquote></div><br><br clear="all"><br>-- <br>“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<br><br>