[Twisted-Python] High-level view of Twisted

[Jason Heeris]

On 1 February 2011 13:58, Kevin Horn <kevin.horn at gmail.com> wrote:
> A couple of us are getting fired up about cleaning up the documentation to
> make it easier for those new to Twisted to find what they're looking for, so
> please do speak up with any feedback you have.

My only suggestion is this: no magic! As per my #1, if an example uses
self.transport, that would be a good time to take the reader aside and
say something like "by the way, self.transport is actually
[description], set in [API link] ... other mysterious attributes you
might need to know about are self.factory, and..."

Even putting that in a special subsection and linking to it would be preferably.

Another example is using "implements" in a class def — I realise it's
from Zope, but there's no harm in explaining it where it's used in an
example.

My $0.02 :)

— Jason