[Twisted-Python] Refactoring Documentation

[Victor Norman]

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>