[Twisted-Python] Evangelism notes...

[Jeff Grimmett]

On 5/6/05, Eugene Coetzee <projects at reedflute.com> wrote:

> 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.


Maybe maybe not. But right now the documentation is like a lightning rod. No 
matter what your agenda, if you want to (for whatever reason) discourage 
against the use of Twisted in a project, all you have to do is point to the 
documentation and the frazzled bunch of geeks trying to figure it all out 
:-)

My experience tells me that basic concepts around the "networking layer"
> is intimidating to a lot of developers.


It would not hurt to have some nice top level documents to address that. 
That's the sort of thing you'd derive from design documentation. 

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 have to disagree on that on a fine point. Twisted is not "open 
source software that happens to be a network framework". It is a "network 
framework that is also open source software". I didn't start looking at 
Twisted because it was open source. I started looking at it because I was 
interested in a better answer than I currently had for networking.

AS SUCH ... I expect the API, like any library I use, to be properly 
documented so I can start using it. I do not wish to investigate the source 
code as a recreational thing. I have a job to do and I want to get it done 
on time, on budget, and done well. Making source code delving a prerequisite 
to use of the software is bad form, in my opinion.

Yes, I find having the source code useful. Usually it's because the 
documentation leaves a fine point unclear; examining the source may resolve 
the confusion. But the source code should not be a crutch to support 
incomplete documentation - not if you want to go toe to toe with the big 
dogs.

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.


:: nod nod nod nod ::

-- 

Best,

Jeff
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://twistedmatrix.com/pipermail/twisted-python/attachments/20050506/179f548e/attachment.htm