[Twisted-Python] Evangelism notes...

[Eugene Coetzee]

Jeff Grimmett wrote:

>
> My unsolicited advice: write the docs either before or during 
> development.
>
dont know why you are so reluctant to say that. It also saves one from 
doing a lot of unproductive coding when the basic design can be put down 
on paper and analysed by peers to eliminate bad ideas from the beginning 
- I suppose that was the original motivation for something like UML - 
please don't shoot me :-)

>
> Here are the pitfalls (as I see them, YMMV) of retroactively writing 
> documentation:
>
> 1) If the person writing the docs is not the person that designed and 
> implemented, the *intent* of the class/module/etc being documented is 
> not clear.
>
> 2) If the person writing the docs is not the person that implemented, 
> then the person that implemented must be found, interrogated, and gone 
> back to multiple times to get the docs right. (And if getting it right 
> is not the goal, why bother?)
>
> 3) If the intent of the module/class/etc is not known beforehand, how 
> does one determine if it is working right?
>
That sums it up pretty well.

> I don't mean to criticize, but this is in my eyes the greatest 
> weakness of Twisted. My experiences with it, when it works, is that it 
> works wonderfully.

Twisted is a superb framework. Once I took a few days of and hacked my 
way through its enigmatic depths I also whispered to myself ... 
eureka... I'm not sure though that documentation is the *only* problem. 
My experience tells me that basic concepts around the "networking layer" 
is intimidating  to a lot of  developers.

> I tell you: if it gets to the point where I SERIOUSLY consider writing 
> my own simple frame work to get a job done as a TIME SAVING MEASURE 
> then there is a problem, and I do not believe I am alone in this 
> perception.
>
I normally ask myself how long will it take to understand this stuff - 
given the state of the documentation. Then I compare it to how long it 
would take to write it myself. Lets be frank - "open source" assumes to 
an extent that you would actually "read the source" as part of the 
documentation. To me the detail (like the API) is not the problem.

I would love to see high level conceptual documentation to give me a 
better idea of  basic concepts  like the "reactor", "application", 
"service", "transport","protocol", "factory" - what they are supposed to 
do and how they are  to fit together.

regards,

Eugene Coetzee

Web                 -> www.reedflute.com
===============================================