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/