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