> Documentation that takes ten pages to say something is just as bad as > documentation that leaves stuff out, because it's almost guaranteed > that it won't be read.
That's the point. If a simple example (6 lines) can demonstrate the concept, why spending "ten pages" to explain it. My experience is that for certain things, it is better describe by a spec once you know it, but it is certainly not true for people to learn it. A reasonable strategy is to interleave spec with demonstrating examples. There is no excuse to not to make the manual easier to read. -- Regards, Peng -- http://mail.python.org/mailman/listinfo/python-list