Speaking just from my own experience, I don't think it's a problem with the docs per se. Rather, I think there's often a disconnect between the answers people are looking for and the nature of Twisted. It's hard to explain, but this is the best I can manage: - If you're used to using frameworks, interfaces reflect your motives when interacting with a library. To use an audio-video (A/V) analogy, you have interfaces like IVolume, IPlayback (play, pause, stop, ff, rew), and IChannel. Documentation just "makes sense". - Twisted is like a box of electronics parts. The docs are enough to see why IDigital and IAnalog are used by DigitalToAnalogConverter, but that's a long way from understanding when you'd even need/care to consume something using an IAnalog. - There are several layers of architecture between a LineReader and a REST library. If you don't realize these layers exist, it's not obvious that you'd need to find/create them in a Twisted app. - The (excellent) krondo tutorial is like a small kit that shows you how to build a model piece of electronics. If you want to build a complete A/V device, where do you go next? To make it more concrete for twisted, here's a example of that next step: - Start with the chat server example ( https://twistedmatrix.com/documents/current/_downloads/chatserver.py) - To add rooms, you need to introduce a layer of commands (minimally JOIN and SEND). This requires a complete rewrite of the Protocol and I'm not aware of any tutorial that helps you make this architectural leap. - Maybe Twisted has a class for this so one might search the docs, spend lots of time, get really confused, and (tentatively) conclude it's not there. Figuring out that something doesn't exist is especially hard. - The authentication example ( https://twistedmatrix.com/documents/current/core/howto/cred.html) actually has a command layer, but key parts of it (i.e. the lineReceived call) are buried in the ellipses. How do you intuit the missing code if you don't even realize that you need a commands layer? - Of course, to combine auth with chat, you also need to figure out how to rewrite the business logic as an IMailbox implementing avatars. That's a LOT of moving pieces to get right at the same time. When I decided to try out Zend Framework (PHP), their full-stack skeleton application ( https://docs.zendframework.com/tutorials/getting-started/skeleton-applicatio...) showed you how everything fit together. Maybe twisted would benefit from something similar... especially if it emphasized the various architectural layers by putting the protocol, command handler, and actual business logic into separate classes. Clayton Daley On Tue, Jul 26, 2016 at 12:58 PM, Glyph Lefkowitz wrote:

On Jul 26, 2016, at 9:37 AM, Daniel Sank wrote:

This is a branch from the thread with subject "Request for help with Twisted bindings in M2Crypt".

Regarding my inability to read documentation:

...

This does at least point to a real problem with pydoctor in the way it presents types. It should probably put them in their own colored box, not use the string 'type' or parentheses to offset them, and put the type closer to (rather than farther from) the parameter name. Would you mind filing a bug on pydoctor? Or commenting on one if it already exists? :)

Done: https://github.com/twisted/pydoctor/issues/121

Thanks! I especially appreciate the screen shot :).

...

...

Some years ago when I tried to understand Twisted's use of interfaces via Twisted's own documentation (which included something about hair dryers and voltage standards) I was puzzled by the fact that the examples didn't really show me how to solve a useful problem (or I was too stupid to understand that the examples did in fact do that) despite the fact that I knew what an interface was in general terms. It was a case of understanding the intent but none of the examples.

...

OK... it's a fair cop.

I'm unfamiliar with that term.

For *me* it's a monty python reference, but I suspect for most speakers of British English, it's just an idiom :). It roughly means "mea culpa", although, more specifically, I believe it means "you've caught me doing something bad".

...

Among other things, it's mainly trying to explain adaptation, which sort of puts the cart before the horse

Yes! That is definitely a big part of the problem. When I think "interface" I think "methods and their signatures an object promises to provided". Adaptation is a detail, so to speak. It's also somewhat confusing that the discussion begins with shapes as it goes over the basic idea of interfaces, and then switches to hair dryers when it comes time for an example. It would be easier to read if the examples were more consistent.

...

and automatic adaptation is increasingly considered spooky action-at-a-distance within Twisted code.

All the more reason to not use adaptation as the in-your-face example.

...

You're the perfect person to submit patches against this doc, by the way, since you have a firm grasp of the whole "abstract interface" thing but also found it confusing.

Perhaps. On the other hand I think it might be better to replace Twisted's own documentation with a link to zope's, or at least put the link at the top and say "read this before reading our examples about adaptation." We'll see if such a patch receives any love.

Please direct my attention to it when one exists :).

-glyph

_______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python