[Twisted-Python] (Summary) The problem with Twisted...

[POYEN OP Olivier (DCL)]

> On the other hand, I think more and better docs for 
> developers (i.e. the
> APIs and "HOWTO"s, which are misnamed I think) is definitely 
> worthwhile.
> The more developers we can attract, the better tested our designs and
> implementation will be, and the better quality our project 
> will become.  At
> the moment, the docs are still somewhat of a barrier to new 
> developers, but
> thankfully not the insurmountable hurdle they used to be :)
> 


If I may, I'd like to add a little something on Docs, from my little newbie point of few:

I've read cl.py a lot, and you can sometimes find people complaining about Twisted Docs.
And the usual response, which does not lack of common sense, is to *not* try to grasp all at the same time, but just go at a specific point, looking for *just* what you want. That's why there are lots of how to. 

But, you know, I'm just the average geek guy, and thus, went to twisted-matrix website, and download and print the whole How-To pdf, with it's 250 pages. 
And, like, I assume, every-one, I try read it first page-> last page. Confusing. 
Yes because there are lots of stuff to get your mind around, but also because you don't want to do that: at many point, you find introdocution stuff in the middle of an how to you would have needed before. 
Let me give an example: 
One of the first thing I read was the "visions" paragraph which quote something like that "in many place in others how-to, you'll find what is twisted; but here let's not speak about that, but let show what It should be". No, on the first page , I want to know what it is !
Then, followed an overview of many components. Great, but I did'nt get yet the whole picture of it (what is it ? What is twisted ?) . Because I need this big picture  before I can put each component in its own box. 
Then I've have a quite excellent overview of twisted enterprise. 
Reallly good, but I still didn't get the whole picture, and I've many details about lot's of other stuff. Even at the beginning of the paragraph, it's written something like 'in order to understand this overview, you should already know how to build a server, what is a reactor....'. It perhaps not quotes exactly that, but you get the point: I read from page one, and you want me to know stuff I did'nt even read yet !

Other example: latter, you have two of the most important how-to: 'make a server'& 'make a client'. 
These one, on the contrary, start very gently. And in the overview, I learn almost what I wanted, to get the "big picture" of twisted: an asynchroneous loop, and after that , no blocking calls, only callback. (maybe I'm wrong). 
Why did I not get those lines in the beginning. It really helps me understanding the big picture of twisted. 

Those commentaries are not agressif, because the docs are just "how to", not a book or a turorial. And those how-to are quite well made.

So, all my point is that the documentation is not so bad, because you did put all the necessary stuff. 
My point is that you need a book, with almost the same content, but a different organization of the data. You need a normal book, cecause people like to have a single entrance point they can read through, linearly.
And I think you should enforce the "try to get the whole thing, the big picture of twisted and then go to a specific point" mantra. 


BTW, I'll be happy to help, and since I'm still a newbie, and since I still did not get twisted , that may be helpful ! 


HTH

OPQ 

-------------- next part --------------
-----------------------------------------------------------------

Ce message est confidentiel ; son contenu ne represente en aucun

cas un engagement de la part de Dexia Credit Local ou de Dexia

CLF Banque. Toute publication, utilisation ou diffusion, meme

partielle, doit etre autorisee prealablement par l'emetteur. Si

vous n'etes pas destinataire de ce message, merci d'en avertir

immediatement l'expediteur.



This message is confidential ; its contents do not constitute a

commitment by Dexia Credit Local or Dexia CLF Banque. Any

unauthorised disclosure, use or dissemination, either whole or

partial, is prohibited. If you are not the intended recipient of

the message, please notify the sender immediately.

-----------------------------------------------------------------

Consultez notre site internet www.dexia-clf.fr

La cle d'une gestion optimisee du secteur public local

-----------------------------------------------------------------