[Twisted-Python] Components

[Christopher Armstrong]

Phillip J. Eby wrote:
> So, when I write something I'm almost invariably thinking about *hard* 
> problems, and that tends to carry over into my documentation.  I'm 
> finding that it's much better to get other people to draft documentation 
> of my stuff, and then edit it for correctness or to show better ways to 
> get the job done, because those other people usually have far more 
> modest goals than I do, and will therefore use simpler examples.  For 
> example, R.D. Murrary wrote a beautiful "Hello World"-driven tutorial 
> for PEAK (at http://peak.telecommunity.com/DevCenter/IntroToPeak/ ) that 
> I could never have written myself because it wouldn't have occurred to 
> me to layer the examples according to complexity of the problem, rather 
> than complexity of the solution.  :)  Contrast IntroToPeak with the 
> PyProtocols docs: the former builds up solutions to bigger and bigger 
> problems, while completely bypassing any discussion of PEAK 
> fundamentals.  Conversely, the PyProtocols doc builds up from tiny 
> little pieces and assembles them into a bigger and bigger framework.  
> That type of documentation is more useful for people developing and 
> extending the framework itself, than for people who want to use it.  So, 
> PyProtocols really needs another R.D. Murray to come along and explain 
> how to do "Hello World" in PyProtocols.  :)

OTOH, I want to say that your documentation does seem very good: when 
the time comes to be go into interstellar abstraction-space, I think it 
will be quite useful. But, indeed, introductory material is very very 
important. :-)


-- 
  Twisted | Christopher Armstrong: International Man of Twistery
   Radix  |          Release Manager,  Twisted Project
---------+           http://radix.twistedmatrix.com/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 256 bytes
Desc: OpenPGP digital signature
URL: </pipermail/twisted-python/attachments/20040226/6bb4ca39/attachment.sig>