[Twisted-Python] Refactoring Documentation

Victor Norman vic.norman at gmail.com
Thu Jan 20 07:43:24 MST 2011


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 <jrennie at gmail.com> wrote:

> 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/
>
>
> _______________________________________________
> Twisted-Python mailing list
> Twisted-Python at 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20110120/bf0c9c00/attachment.html>


More information about the Twisted-Python mailing list