[Twisted-Python] Components

[Phillip J. Eby]

At 07:34 PM 2/26/04 -0500, Christopher Armstrong wrote:
>Phillip J. Eby wrote:
>>Stop trying to understand it and just use it.  ;)  Seriously, though, I 
>>think that Twisted's Interface/Adapter How-To is the kind of 
>>documentation I *should* have written for PyProtocols.  The PyProtocols 
>>docs were biased towards proving that its framework is consistent and 
>>useful for all sorts of tricky edge cases and advanced interface usages, 
>>instead of just saying, "here, this is what you can do".  In particular, 
>>I wanted to show Jim Fulton that adaptation is more fundamental than 
>>interface implementation, because you can represent the latter as a 
>>special case of the former.  (i.e., the NO_ADAPTER_NEEDED adapter.)
>>So, as you can see right there, writing docs with Jim Fulton in mind as 
>>the intended audience is where I made my big mistake.  :)
>
>Hmm, yeah, I think it would be helpful to have a document that mixes 1) 
>explanation of interfaces/adaptors and why you need them and 2) basic 
>introduction to PyProtocols to do what is outlined in #1. This is 
>basically what the Twisted components howto is, but the Twisted components 
>howto is pretty crappy, IMO :-) There's a lot of room for improvement in 
>it even in that limited scope.

Yeah, my problem is that I don't usually write stuff to solve simple 
problems, because if it was a simple problem, somebody else would probably 
have already written something to solve it, and I could just download their 
implementation and be done with it.  :)

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