[Twisted-Python] Teach Me Twisted Redux
I'd just like to thank the Twisted community for their support in yesterday's "Teach Me Twisted" Open Space session. To see the room still half-full of people talking animatedly about Python twenty minutes after the session ended was a great tribute to how interested people are in making Twisted work for them, and a reminder of what PyCon is all about. I haven't ever enjoyed any PyCon activity so much. Couldn't have done it without you,guys, thanks a million. regards Steve -- Steve Holden +1 571 484 6266 +1 800 494 3119 Holden Web LLC http://www.holdenweb.com/
On Sun, Mar 16, 2008 at 2:33 PM, Steve Holden <steve@holdenweb.com> wrote:
I'd just like to thank the Twisted community for their support in yesterday's "Teach Me Twisted" Open Space session. To see the room still half-full of people talking animatedly about Python twenty minutes after the session ended was a great tribute to how interested people are in making Twisted work for them, and a reminder of what PyCon is all about. I haven't ever enjoyed any PyCon activity so much.
Couldn't have done it without you,guys, thanks a million.
It was great fun for us too, Steve -- thanks for coming up with such a great idea/format for an open space session/tutorial! d
On Sun, 16 Mar 2008 14:33:26 -0500, Steve Holden <steve@holdenweb.com> wrote:
I'd just like to thank the Twisted community for their support in yesterday's "Teach Me Twisted" Open Space session. To see the room still half-full of people talking animatedly about Python twenty minutes after the session ended was a great tribute to how interested people are in making Twisted work for them, and a reminder of what PyCon is all about. I haven't ever enjoyed any PyCon activity so much.
I heartily concur, it was a lot of fun, and if anything, even more fun once we all retired to the bar.
Couldn't have done it without you,guys, thanks a million.
My thanks to you for being such a good sport. L. Daniel Burr
This session was really fabulous, and it's unfortunate that Steve will be a Twisted expert in short order, making it a once-in-a-lifetime opportunity. It was probably the high point of PyCon for me this year as well. Thanks a lot for doing it. I really felt like having a presenter who wasn't afraid to admit that they didn't know what they were doing either really reduced the impression that Twisted is this impossibly hard thing to learn quite a bit. And we really covered a fair amount of material. Next year, we should definitely have more regular Twisted talks; I'd say that someone else should do another "teach me twisted" session, but I don't know if anyone else has the raw charisma and pedagogical expertise that Mr. Holden combined with Twisted ignorance to make this session so great :). On 16 Mar, 07:33 pm, steve@holdenweb.com wrote:
I'd just like to thank the Twisted community for their support in yesterday's "Teach Me Twisted" Open Space session. To see the room still half-full of people talking animatedly about Python twenty minutes after the session ended was a great tribute to how interested people are in making Twisted work for them, and a reminder of what PyCon is all about. I haven't ever enjoyed any PyCon activity so much.
Couldn't have done it without you,guys, thanks a million.
regards Steve -- Steve Holden +1 571 484 6266 +1 800 494 3119 Holden Web LLC http://www.holdenweb.com/
_______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
glyph@divmod.com wrote:
This session was really fabulous, and it's unfortunate that Steve will be a Twisted expert in short order, making it a once-in-a-lifetime opportunity.
It was probably the high point of PyCon for me this year as well. Thanks a lot for doing it. I really felt like having a presenter who wasn't afraid to admit that they didn't know what they were doing either really reduced the impression that Twisted is this impossibly hard thing to learn quite a bit. And we really covered a fair amount of material.
As I believe I mentioned early on, one of the issues is that the Twisted core developers are so smart (I believe I may have used the phrase "brains the size of planets"), and so knowledgeable about Twisted, that it's difficult sometimes to get a 90% answer out of them. This was particularly the case with Itamar, whom I lambasted quite mercilessly (and whom I therefore owe a public apology: sorry, Itamar) when he tried to complete all the corner cases after a slightly inaccurate statement on my part that was perfectly good enough for a learner. Think about driving a car: "never use the brake and the accelerator together" is a good rule for learners, and it isn't helpful to then have someone say "except if you want to put the car in a 180% power slide" -- not because it isn't true, but because you definitely need more than a couple of days' experience before undertaking that maneuver (God, American really mangles that word), and most drivers will never need it in a lifetime. I left the session feeling we had accomplished hardly anything, but was persuaded afterwards that wasn't the case. One of the tragedies of the session was due to the blue screen crash of my own computer I have absolutely nothing left of the code we developed. I had hopes that one or two blog entries might appear to allow me to lift it from those attending, but so far the success of the session is a closely guarded secret among PyCon attendees (thought it's been gratifying to have people saying "I wished I'd gone to that"). If someone can provide me with the code I will undertake to produce some sort of blog entry, and this might further publicize Twisted. Never underestimate the value of marketing: the Twisted community is a subset of the Python community, and it's my particular vanity that PyCon has helped to increase the Python community. It's important to keep feeding introductory material into the process as growth continues, because typically 50% of those present are likely to be newbies. In point of fact this type of session *might* work with pretended ignorance, but it wouldn't have the same honesty, and I think that honesty *could* make the learning experience more powerful. Anyway the PyCon organizers list seems to have got fired up about it, so there's a good chance that there'll be more "Teach Me ..." sessions next year.
Next year, we should definitely have more regular Twisted talks; I'd say that someone else should do another "teach me twisted" session, but I don't know if anyone else has the raw charisma and pedagogical expertise that Mr. Holden combined with Twisted ignorance to make this session so great :).
Don't forget the whisky ... I hope this actually marks my entrance proper into the Twisted community, to whom I owe a great debt for the success of PyCon. Your initial energy and enthusiasm (as I remember it, PyCon represented the first major opportunity for the Twisted team to have a more or less all-hands meeting) was responsible in large part for shaping the PyCon experience, to the extent that the spirit lived on even after the Twisted contingent departed due to ... well, I guess you guys just got busy with DivMod and the like. I missed you. It goes to show, we often don't appreciate the positive influence we have on events. But you are more than welcome, consider it payback and pass it on. What we possibly need first of all is for someone to do a "Teach Me Teach Me" in the tutorial track, with myself and a number of the more experienced trainer types as the "subject matter experts". These things are always one-off in nature and it's unrealistic to expect that they will all have the same charm as "Teach Me Twisted" did this year for all the reasons I mention above, but if it gets information out more effectively about "difficult" topics it's probably worth a try if we can find someone to facilitate them. regards Steve
On 16 Mar, 07:33 pm, steve@holdenweb.com wrote:
I'd just like to thank the Twisted community for their support in yesterday's "Teach Me Twisted" Open Space session. To see the room still half-full of people talking animatedly about Python twenty minutes after the session ended was a great tribute to how interested people are in making Twisted work for them, and a reminder of what PyCon is all about. I haven't ever enjoyed any PyCon activity so much.
Couldn't have done it without you,guys, thanks a million.
regards Steve
On Thu, 2008-03-20 at 07:33 -0400, Steve Holden wrote:
glyph@divmod.com wrote: As I believe I mentioned early on, one of the issues is that the Twisted core developers are so smart (I believe I may have used the phrase "brains the size of planets"), and so knowledgeable about Twisted, that it's difficult sometimes to get a 90% answer out of them. This was particularly the case with Itamar, whom I lambasted quite mercilessly (and whom I therefore owe a public apology: sorry, Itamar) when he tried to complete all the corner cases after a slightly inaccurate statement on my part that was perfectly good enough for a learner.
There is a great deal of anecdotal evidence that great players make poor coaches. One of the biggest (glaring?) issues with Twisted is the abysmal state of the documentation (none) making the code the best source... and history is replete with the massive successes that approach has borne... What documentation there is includes: "If you need to call a method that returns a deferred within your callback chain, just return that deferred, and the result of the secondary deferred's processing chain will become the result that gets passed to the next callback of the primary deferreds processing chain" Now, the above is true and clear to those of us who know twisted... but I've used that quote for levity... its simply incomprehensible... but absolutely critical to understanding the power of twisted. I'd say that the current state of twisted documentation is in part represented by that quote... and much of the reason twisted gets thrown out early as an option. (yet this same group complains that Git is too complex to be used for source code control... even though its core architecture eclipses the alternatives being used and considered...) Clearly, the issues Twisted addresses are non-trivial requiring an appreciation of the problem space before considering Twisted as a solution (you gotta know there's a question before someone tells you the answer)... unfortunately, the barrier to Twisted entry at that point makes most walk away. I've seen lots of threads concluding, simply, that twisted looked interesting but was simply too dense to even get started with... so, they go ahead and roll their own solution, inevitably identifying the issues which form heart of the twisted architecture, but being too far along to refactor. And away we go. Exacerbating the problem is the state of the twisted code base. The core itself is clean, high performance and great. But, there's a large percentage of the code base in various states of decay. Some clearly marked as no longer supported... but most simply marked "undocumented" and much of the rest necessitating querying #twisted, hopefully at a time when someone is available to answer questions... twisted-web appears to be worse from a documentation perspective and I'm one of those who chose to "just walk away" when a web framework was necessary. For example, I've been playing with Twisted for a while now and only recently stumbled upon AMP... perhaps thats a personal issue and I do have fundamental intelligence limitations... but perhaps its illustrative.
What we possibly need first of all is for someone to do a "Teach Me Teach Me" in the tutorial track, with myself and a number of the more experienced trainer types as the "subject matter experts". These things are always one-off in nature and it's unrealistic to expect that they will all have the same charm as "Teach Me Twisted" did this year for all the reasons I mention above, but if it gets information out more effectively about "difficult" topics it's probably worth a try if we can find someone to facilitate them.
What we need is a core documentation / presentation / communication strategy to communicate what twisted is and a vehicle to support education. Handling conferences is a degenerate case which requires extension with malt beverages.
regards Steve
On 16 Mar, 07:33 pm, steve@holdenweb.com wrote:
I'd just like to thank the Twisted community for their support in yesterday's "Teach Me Twisted" Open Space session. To see the room still half-full of people talking animatedly about Python twenty minutes after the session ended was a great tribute to how interested people are in making Twisted work for them, and a reminder of what PyCon is all about. I haven't ever enjoyed any PyCon activity so much.
Couldn't have done it without you,guys, thanks a million.
regards Steve
_______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
-- Glenn H. Tarbox, PhD 206-494-0819 glenn@tarbox.org
On Thu, Mar 20, 2008 at 11:36 AM, Glenn H Tarbox, PhD <glenn@tarbox.org> wrote:
One of the biggest (glaring?) issues with Twisted is the abysmal state of the documentation (none) making the code the best source... and history is replete with the massive successes that approach has borne...
Clearly, the issues Twisted addresses are non-trivial requiring an appreciation of the problem space before considering Twisted as a solution (you gotta know there's a question before someone tells you the answer)... unfortunately, the barrier to Twisted entry at that point makes most walk away. I've seen lots of threads concluding, simply, that twisted looked interesting but was simply too dense to even get started with... so, they go ahead and roll their own solution, inevitably identifying the issues which form heart of the twisted architecture, but being too far along to refactor. And away we go.
Exacerbating the problem is the state of the twisted code base. The core itself is clean, high performance and great. But, there's a large percentage of the code base in various states of decay. Some clearly marked as no longer supported... but most simply marked "undocumented" and much of the rest necessitating querying #twisted, hopefully at a time when someone is available to answer questions... twisted-web appears to be worse from a documentation perspective and I'm one of those who chose to "just walk away" when a web framework was necessary.
For example, I've been playing with Twisted for a while now and only recently stumbled upon AMP... perhaps thats a personal issue and I do have fundamental intelligence limitations... but perhaps its illustrative.
This is indeed a shame. I come to Twisted an experienced Ruby and Java developer in need for a event-driven networking framework. I had taken a close look at ruby's EventMachine, which is modeled after Twisted, but was strongly leaning towards Twisted *for* the documentation (and the apparent stability and age of the project). At the very least, Twisted has an Oreilly book and docs on the website (EM only provides rdoc). So, I bought the Oreilly book and Python in a Nutshell. I've made it through the Nutshell book (I spent 3 months doing python back in 2003, so it's not completely new to me). My next steps include the book first and online docs second...but now am I to understand that both are useless? Should I just dive into the code instead? Here's to hoping at least the concepts are introduced effectively... John
On Thursday 20 March 2008, John Wells wrote:
So, I bought the Oreilly book and Python in a Nutshell. I've made it through the Nutshell book (I spent 3 months doing python back in 2003, so it's not completely new to me). My next steps include the book first and online docs second...but now am I to understand that both are useless? Should I just dive into the code instead?
Although they are not perfect, they are certainly not useless. The snake ball book gives a lot of examples of things you can do with Twisted. It doesn't go very deep into the fundamentals: deferreds, transports, protocols and Zope interfaces are all important building blocks in Twisteed and of these, only deferreds are explained in some detail. It doesn't go very deep into web servers either, but that's not really the book's fault (page 54 explains the problem). The book is from 2005, so recent developments like inlineCallbacks and AMP are not in it. All in all, the book is quite useful in my opinion if you want to get a quick start implementing some kind of server or client using Twisted. Just don't expect that this book is all you'll need. As for the online docs, the "finger" tutorial was very effective for me in demonstrating the power of Twisted: how you can get a lot of functionality in only a few lines of code. And it also shows that this power comes from modular design with good interfaces, not from having "skinnable" implementations that become useless as soon as you want to do something slightly different. The explanation of deferreds is also decent in my opinion. It took me a while to really grasp it, but that's probably more of a lack of experience in asynchronous programming than a deficiency of the documentation. The API docs are better than many other open source projects have them. However, because Twisted is a large collection of small modules and highly abstract in places, the API docs are only useful if you know what you are looking for. As for reading the source code, for most projects that translates to "you're out of luck", but the Twisted source code is actually surprisingly easy to read. It has the same problem as the API docs though: if you don't know what you are looking for exactly, it's unlikely you'll find it. Some documentation I would like to read: - what is the point of the Zope interfaces? is it mainly for documentation purposes? I read some things about being able to automatically adapt from one interface to another, but where is that used in practice? the only thing I used it for so far is to attach information to an HTTP session object - the design behind "cred", especially the authorization part: what exactly is an avatar, how do you implement one and how do you use one? - the design behind taps: what is a tap exactly? why all the different types? does it require serialization or could I write one by hand? how should my program be written to be "tappable"? - what is AMP and in what way is it different from PB, foolscap, xmlrpc? If this already exists, please point me to it. Otherwise, if you know something about the subject and would like to write about it, I would really appreciate it. If there is any documentation I can proof read or edit, please let me know. I've been using Twisted for a couple of years, but I have only seen very small parts of its API, so writing a document from scratch would take too much time, but I'm willing to take on smaller tasks. Bye, Maarten
On 20 Mar, 06:08 pm, lists@sourceillustrated.com wrote:
So, I bought the Oreilly book and Python in a Nutshell. I've made it through the Nutshell book (I spent 3 months doing python back in 2003, so it's not completely new to me). My next steps include the book first and online docs second...but now am I to understand that both are useless? Should I just dive into the code instead?
No, absolutely not. We have a useful FAQ and some useful tutorial documents. For example, Moshe Zadka's "finger" tutorial (while not perfect) is an excellent example of how to use Twisted, and its multi-layered approach: http://twistedmatrix.com/projects/core/documentation/howto/tutorial/index.ht... This is the first google hit for "twisted tutorial". The first google hit for "writing servers", by the way: http://twistedmatrix.com/projects/core/documentation/howto/servers.html is a great low-level introduction to Twisted's core concepts. Of course, like any large project, the documentation for different parts of Twisted is going to vary a lot. But it would be a gross overstatement to say there's no documentation or that it's completely useless.
On Thu, Mar 20, 2008 at 11:36 AM, Glenn H Tarbox, PhD <glenn@tarbox.org> wrote:
On Thu, 2008-03-20 at 07:33 -0400, Steve Holden wrote:
glyph@divmod.com wrote: As I believe I mentioned early on, one of the issues is that the Twisted core developers are so smart (I believe I may have used the phrase "brains the size of planets"), and so knowledgeable about Twisted, that it's difficult sometimes to get a 90% answer out of them. This was particularly the case with Itamar, whom I lambasted quite mercilessly (and whom I therefore owe a public apology: sorry, Itamar) when he tried to complete all the corner cases after a slightly inaccurate statement on my part that was perfectly good enough for a learner.
There is a great deal of anecdotal evidence that great players make poor coaches.
One of the biggest (glaring?) issues with Twisted is the abysmal state of the documentation (none) making the code the best source... and history is replete with the massive successes that approach has borne...
I think "abysmal" is really an overstatement. A lot of external documentation for Twisted exists (http://twistedmatrix.com/projects/core/documentation/howto/index.html) - though some of it is indeed too esoteric for the casual beginner. The twisted team realizes this and they are improving the documentation and setting high standards for documenting new additions to the library - take the initial doc string for amp as an example.
(yet this same group complains that Git is too complex to be used for source code control... even though its core architecture eclipses the alternatives being used and considered...)
Tangential, but I know of at least two Twisted developers who are using Git. The evaluation of version control tools usually includes whether or not the tool works across platforms well - Git does not eclipse the alternatives in this category.
For example, I've been playing with Twisted for a while now and only recently stumbled upon AMP... perhaps thats a personal issue and I do have fundamental intelligence limitations... but perhaps its illustrative.
Agreed, AMP needs some external documentation alongside PB in the main documentation page. Maybe I'll contribute a document myself - unless someone else is already working on such? -, since I find myself using amp a lot these days. There are instances when you want access to remote objects where PB (or the newer foolscap) are great for - but for functional command-dispatch based RPC, amp really shines.
What we need is a core documentation / presentation / communication strategy to communicate what twisted is and a vehicle to support education. Handling conferences is a degenerate case which requires extension with malt beverages.
Which takes time (writing good documentation is arguably harder than writing good code) - and community support. And time is money ... so contribute to Twisted so they can hire more documentation experts :-) -- \\\\\/\"/\\\\\\\\\\\ \\\\/ // //\/\\\\\\\ \\\/ \\// /\ \/\\\\ \\/ /\/ / /\/ /\ \\\ \/ / /\/ /\ /\\\ \\ / /\\\ /\\\ \\\\\/\ \/\\\\\/\\\\\/\\\\\\ d.p.s
Drew Smathers wrote:
On Thu, Mar 20, 2008 at 11:36 AM, Glenn H Tarbox, PhD <glenn@tarbox.org> wrote:
On Thu, 2008-03-20 at 07:33 -0400, Steve Holden wrote:
glyph@divmod.com wrote: As I believe I mentioned early on, one of the issues is that the Twisted core developers are so smart (I believe I may have used the phrase "brains the size of planets"), and so knowledgeable about Twisted, that it's difficult sometimes to get a 90% answer out of them. This was particularly the case with Itamar, whom I lambasted quite mercilessly (and whom I therefore owe a public apology: sorry, Itamar) when he tried to complete all the corner cases after a slightly inaccurate statement on my part that was perfectly good enough for a learner.
There is a great deal of anecdotal evidence that great players make poor coaches.
One of the biggest (glaring?) issues with Twisted is the abysmal state of the documentation (none) making the code the best source... and history is replete with the massive successes that approach has borne...
Just let me interject here that I believe the attributions above make it look like *I* wrote the above. It doesn't align with my understanding of Twisted's documentation, which in my assessment has improved immensely over five years.
Sure enough, Glenn H Tarbox was the perpetrator: throw your rotten fruit at him, not me. I'm a *friend* of Twisted, for Pete's sake. regards Steve
On 20 Mar, 06:31 pm, steve@holdenweb.com wrote:
Sure enough, Glenn H Tarbox was the perpetrator: throw your rotten fruit at him, not me. I'm a *friend* of Twisted, for Pete's sake.
I believe the honorable Dr. Tarbox actually qualifies as a Bronze founding sponsor of the TSF, so at this point I don't think he's yet overstepped the amount of crap he's allowed to give us. Although perhaps future vitriol could be saved for the sponsors list we are in the process of setting up, and in the more productive form of feature requests :). (Thanks, Glenn! Do you want to send us a logo, perhaps a signature, to put on the front page?)
glyph@divmod.com wrote:
I believe the honorable Dr. Tarbox actually qualifies as a Bronze founding sponsor of the TSF, so at this point I don't think he's yet overstepped the amount of crap he's allowed to give us. Although perhaps future vitriol could be saved for the sponsors list we are in the process of setting up, and in the more productive form of feature requests :).
(Thanks, Glenn! Do you want to send us a logo, perhaps a signature, to put on the front page?)
I notice that the TSF has no Gold sponsors yet ... perhaps, judging from an aside made at the Teach-Me-Twisted session by a certain Google fellow (who happens to be a venerated, well-known Python roshi ;), perhaps Google should be Twisted's first Gold sponsor ... anyone from Google listening? :) Cheers, Steve
On 02:34 am, waterbug@pangalactic.us wrote:
I notice that the TSF has no Gold sponsors yet ... perhaps, judging from an aside made at the Teach-Me-Twisted session by a certain Google fellow (who happens to be a venerated, well-known Python roshi ;), perhaps Google should be Twisted's first Gold sponsor ... anyone from Google listening? :)
Zenoss will be our first Gold sponsor. We're still figuring out payment details with them right now, we're new to this whole "accepting money" thing. Also, Gold isn't the highest level. If you want to find out what the highest level is, just contribute geometrically increasing amounts of money and see if we put you into a new category. We are working on talking to Google, among other folks. I can only send so many emails in one day. And in fact I'm in the process of precisely discovering that limit ;-).
On Mar 20, 2008, at 11:36 AM, Glenn H Tarbox, PhD wrote:
One of the biggest (glaring?) issues with Twisted is the abysmal state of the documentation (none) making the code the best source... and history is replete with the massive successes that approach has borne...
What documentation there is includes: "If you need to call a method that returns a deferred within your callback chain, just return that deferred, and the result of the secondary deferred's processing chain will become the result that gets passed to the next callback of the primary deferreds processing chain"
Now, the above is true and clear to those of us who know twisted... but I've used that quote for levity... its simply incomprehensible... but absolutely critical to understanding the power of twisted. I'd say that the current state of twisted documentation is in part represented by that quote... and much of the reason twisted gets thrown out early as an option.
I think there's a lot of truth to this, but you can say the same thing about a vast number of open source projects. Not that it's an excuse, of course, but in most of the projects I can think of that have sufficient documentation, such a thing didn't occur until the software reached a critical mass of users. The Twisted community is growing all the time, but it's still just a part of the Python community, which despite a number of high-profile Python projects, is still eclipsed by Java, Perl and (*shudder*) PHP. As for the complexity of docstrings, I don't think anyone should be considering source code documentation equivalent to a formal tutorial, so I think the brevity (and assumption of existing knowledge) is pretty much warranted in that case.
Clearly, the issues Twisted addresses are non-trivial requiring an appreciation of the problem space before considering Twisted as a solution (you gotta know there's a question before someone tells you the answer)... unfortunately, the barrier to Twisted entry at that point makes most walk away. I've seen lots of threads concluding, simply, that twisted looked interesting but was simply too dense to even get started with... so, they go ahead and roll their own solution, inevitably identifying the issues which form heart of the twisted architecture, but being too far along to refactor. And away we go.
I completely agree with the first half of this paragraph, but I have a different perspective on the second. I've been lurking on this mailing list for years, and what I see most often is people who do not even begin to understand the concept of asynchronous networking. *This* is the barrier to entry, and it's almost always the culprit when a potential user walks away from Twisted. IIRC, at the time Twisted Python was created, thread support in Python was simply awful. Threads were absolutely not a solution for dealing with multiple client connections to a server application, and the only alternative was asyncore. As many of you may remember, asyncore was not great, but it *was* simple. Writing an asyncore application required knowledge of maybe three different classes, so while you were working on understanding asynchronous networking, you didn't have to deal with learning a vast new API. The problem I've seen with various responses from seasoned Twisted devs to unexperienced developers is that one can only explain why you don't want to use any kind of long-blocking call so many times. After that, answers start becoming glib and/or overly terse, but I can't really blame anyone for that. There are a few introductory tutorials on asynchronous programming, but we could always use more. I almost wonder if it would be worthwhile to have an asyncore tutorial as the first step, so that users can be exposed to asynchronous programming through a simpler model, run into some problems, and then see how Twisted makes them all go away.
Exacerbating the problem is the state of the twisted code base. The core itself is clean, high performance and great. But, there's a large percentage of the code base in various states of decay. Some clearly marked as no longer supported... but most simply marked "undocumented" and much of the rest necessitating querying #twisted, hopefully at a time when someone is available to answer questions... twisted-web appears to be worse from a documentation perspective and I'm one of those who chose to "just walk away" when a web framework was necessary.
I definitely agree with you about the state of Twisted.Web. I think the culprit here is not entirely a shortage of documentation. The real problem is Web2. Now, I am the last person to discourage total or near-total rewrites of stable codebases. I know I personally have made the choice to rewrite projects instead of fixing the things that are broken on a number of occasions, but the creation of the Web2 initiative has caused endless problems when explaining Twisted's web features to new users. There's lots of good stuff in Web2, but its existence as a half- supported, half-unreleased project causes much confusion to new users, probably because they always assume that it's a choice between Twisted.Web 1.0 and Twisted.Web 2.0, which is obviously not the case. The web situation is also exacerbated in some ways by Nevow being a separate project under the Divmod banner. Much of the greatness of a Twisted web stack (IMO) comes from using it with Nevow, and in this AJAX-crazed world we live in, Nevow.Athena could easily sell the whole web layer to anyone working on a heavily AJAX-oriented project. Finally, now imagine yourself as a web developer who has never had to deal with asynchronous programming, or Twisted, or Twisted.Web; you don't know whether you should use web2 or not, and you've never heard of Athena. Obviously, there's good reasons why these various things have happened over the years, but I really think documentation isn't enough to fix organizational issues. And, given the state of flux (apparent or actual) in the Twisted.Web arena, who wants to write extensive documentation that will be completely broken in a year? (We all know why that line of thought is wrong, but it doesn't make it any less common...)
For example, I've been playing with Twisted for a while now and only recently stumbled upon AMP... perhaps thats a personal issue and I do have fundamental intelligence limitations... but perhaps its illustrative.
I have to say, I still don't really know what AMP is, and I've asked a bunch of times. Maybe I actually do know, by now, but I've certainly forgotten.
What we need is a core documentation / presentation / communication strategy to communicate what twisted is and a vehicle to support education. Handling conferences is a degenerate case which requires extension with malt beverages.
I really think that doing this properly requires a core team of people at least as large as the core Twisted dev group. They would need to have both a knack for documentation and an understanding of somewhat low-level networking concepts, *and* an ability to read source code effectively. Now, I don't mean to point out obstacles and say it's hopeless, but I think this relates to the critical mass I was talking about earlier. I think Twisted just needs to reach that level where there's enough people who want to write documentation that it gets done. Other attempts to force the issue haven't really met with much success; I know there used to be (perhaps still are) a few bounties out there on documentation, but not much has happened in that arena since then. (Personally, I am anti-bounty, as I feel -- perhaps irrationally so -- that it cheapens the hours and hours of work that people have done for free.) I think the best way for us to address this in the short term is to really try to focus on group documentation. The current Trac wiki can barely be called collaborative; as a start why not transfer the Twisted docs into the wiki, and allow Trac users to modify and update this information? Furthermore, considering the length some of the posts I see here, I'd like to suggest that if you're going to spend 30 minutes writing an email explaining some concept, why not write a mini tutorial about it instead? Even if you just copy and paste the email you were going to send into the wiki, it's still a start, and others can work on it from there. You know what they say about documentation being like sex; when it's good it's great, but when it's bad it's still better than nothing ;-)... -phil
Phil Christensen wrote:
On Mar 20, 2008, at 11:36 AM, Glenn H Tarbox, PhD wrote:
One of the biggest (glaring?) issues with Twisted is the abysmal state of the documentation (none) making the code the best source... and history is replete with the massive successes that approach has borne...
What documentation there is includes: "If you need to call a method that returns a deferred within your callback chain, just return that deferred, and the result of the secondary deferred's processing chain will become the result that gets passed to the next callback of the primary deferreds processing chain"
Well, perhaps we can extend the conference session a little. [Drinks whisky].
So what you are saying is that a callback can find itself needing to return a result that is not yet immediately available. So it will return a deferred, whose callbacks and errbacks will be triggered in the standard way when the result becomes available ... [Drinks more whisky]. Did Itamar write this? HELP!
Now, the above is true and clear to those of us who know twisted... but I've used that quote for levity... its simply incomprehensible... but absolutely critical to understanding the power of twisted. I'd say that the current state of twisted documentation is in part represented by that quote... and much of the reason twisted gets thrown out early as an option.
I believe you've made your point, and one of the reasons I chose Twisted as the topic for the session was because the document doesn't show, if I may briefly channel Zed Shaw, how truly fucking amazing Twisted is. The good news: this is a remediable deficiency. The bad news: it has neither the glamor nor the appeal of hacking at the codeface. Now you have a Foundation, consider having it sponsor (through the PSF is you aren't registered as a mentoring organization) someone to work on the docs in Summer of Code. Even trawling the mailing lists for useful material would yield some gems that could be used to improve things.
I think there's a lot of truth to this, but you can say the same thing about a vast number of open source projects. Not that it's an excuse, of course, but in most of the projects I can think of that have sufficient documentation, such a thing didn't occur until the software reached a critical mass of users.
The Twisted community is growing all the time, but it's still just a part of the Python community, which despite a number of high-profile Python projects, is still eclipsed by Java, Perl and (*shudder*) PHP.
Some things are simply better not documented.
As for the complexity of docstrings, I don't think anyone should be considering source code documentation equivalent to a formal tutorial, so I think the brevity (and assumption of existing knowledge) is pretty much warranted in that case.
Clearly, the issues Twisted addresses are non-trivial requiring an appreciation of the problem space before considering Twisted as a solution (you gotta know there's a question before someone tells you the answer)... unfortunately, the barrier to Twisted entry at that point makes most walk away. I've seen lots of threads concluding, simply, that twisted looked interesting but was simply too dense to even get started with... so, they go ahead and roll their own solution, inevitably identifying the issues which form heart of the twisted architecture, but being too far along to refactor. And away we go.
I completely agree with the first half of this paragraph, but I have a different perspective on the second.
I've been lurking on this mailing list for years, and what I see most often is people who do not even begin to understand the concept of asynchronous networking. *This* is the barrier to entry, and it's almost always the culprit when a potential user walks away from Twisted.
That's true, and I tried to get this across using the analogy of a GUI interface to explain the event-driven nature of Twisted. This was fine for people who had done GUI programming, but Glyph later gave me an email analogy which would work far better for those who hadn't. One of the distinguishing features of *great* documentation is that it provides the same information in ways that make it accessible to different audiences.
IIRC, at the time Twisted Python was created, thread support in Python was simply awful. Threads were absolutely not a solution for dealing with multiple client connections to a server application, and the only alternative was asyncore.
And Twisted is still a way better solution even now.
As many of you may remember, asyncore was not great, but it *was* simple. Writing an asyncore application required knowledge of maybe three different classes, so while you were working on understanding asynchronous networking, you didn't have to deal with learning a vast new API.
The problem I've seen with various responses from seasoned Twisted devs to unexperienced developers is that one can only explain why you don't want to use any kind of long-blocking call so many times. After that, answers start becoming glib and/or overly terse, but I can't really blame anyone for that.
Except those who failed to extract the kernel of these three thousand answers and incorporate it into the documentation. If it's a failure it's a common one, and it's distributed throughout the community.
There are a few introductory tutorials on asynchronous programming, but we could always use more. I almost wonder if it would be worthwhile to have an asyncore tutorial as the first step, so that users can be exposed to asynchronous programming through a simpler model, run into some problems, and then see how Twisted makes them all go away.
Exacerbating the problem is the state of the twisted code base. The core itself is clean, high performance and great. But, there's a large percentage of the code base in various states of decay. Some clearly marked as no longer supported... but most simply marked "undocumented" and much of the rest necessitating querying #twisted, hopefully at a time when someone is available to answer questions... twisted-web appears to be worse from a documentation perspective and I'm one of those who chose to "just walk away" when a web framework was necessary.
I definitely agree with you about the state of Twisted.Web. I think the culprit here is not entirely a shortage of documentation. The real problem is Web2.
Now, I am the last person to discourage total or near-total rewrites of stable codebases. I know I personally have made the choice to rewrite projects instead of fixing the things that are broken on a number of occasions, but the creation of the Web2 initiative has caused endless problems when explaining Twisted's web features to new users.
There's lots of good stuff in Web2, but its existence as a half-supported, half-unreleased project causes much confusion to new users, probably because they always assume that it's a choice between Twisted.Web 1.0 and Twisted.Web 2.0, which is obviously not the case.
The web situation is also exacerbated in some ways by Nevow being a separate project under the Divmod banner. Much of the greatness of a Twisted web stack (IMO) comes from using it with Nevow, and in this AJAX-crazed world we live in, Nevow.Athena could easily sell the whole web layer to anyone working on a heavily AJAX-oriented project.
Finally, now imagine yourself as a web developer who has never had to deal with asynchronous programming, or Twisted, or Twisted.Web; you don't know whether you should use web2 or not, and you've never heard of Athena.
Obviously, there's good reasons why these various things have happened over the years, but I really think documentation isn't enough to fix organizational issues. And, given the state of flux (apparent or actual) in the Twisted.Web arena, who wants to write extensive documentation that will be completely broken in a year?
Nobody. If anyone offers, back away, smiling.
(We all know why that line of thought is wrong, but it doesn't make it any less common...)
For example, I've been playing with Twisted for a while now and only recently stumbled upon AMP... perhaps thats a personal issue and I do have fundamental intelligence limitations... but perhaps its illustrative.
I have to say, I still don't really know what AMP is, and I've asked a bunch of times. Maybe I actually do know, by now, but I've certainly forgotten.
What we need is a core documentation / presentation / communication strategy to communicate what twisted is and a vehicle to support education. Handling conferences is a degenerate case which requires extension with malt beverages.
I really think that doing this properly requires a core team of people at least as large as the core Twisted dev group. They would need to have both a knack for documentation and an understanding of somewhat low-level networking concepts, *and* an ability to read source code effectively.
Now, I don't mean to point out obstacles and say it's hopeless, but I think this relates to the critical mass I was talking about earlier. I think Twisted just needs to reach that level where there's enough people who want to write documentation that it gets done.
Other attempts to force the issue haven't really met with much success; I know there used to be (perhaps still are) a few bounties out there on documentation, but not much has happened in that arena since then. (Personally, I am anti-bounty, as I feel -- perhaps irrationally so -- that it cheapens the hours and hours of work that people have done for free.)
I think the best way for us to address this in the short term is to really try to focus on group documentation. The current Trac wiki can barely be called collaborative; as a start why not transfer the Twisted docs into the wiki, and allow Trac users to modify and update this information?
Furthermore, considering the length some of the posts I see here, I'd like to suggest that if you're going to spend 30 minutes writing an email explaining some concept, why not write a mini tutorial about it instead?
[Is that the sun starting to brighten the night sky over the horizon?]
Even if you just copy and paste the email you were going to send into the wiki, it's still a start, and others can work on it from there.
You know what they say about documentation being like sex; when it's good it's great, but when it's bad it's still better than nothing ;-)...
And when you haven't had any for years you will even read the Twisted documentation ;-) regards Steve
On 20 Mar, 06:27 pm, phil@bubblehouse.org wrote:
I've been lurking on this mailing list for years, and what I see most often is people who do not even begin to understand the concept of asynchronous networking. *This* is the barrier to entry, and it's almost always the culprit when a potential user walks away from Twisted.
Yes. We need more intermediate users to help the beginners. The problem with the Twisted dev team is that we now have a collection of amazing, unbelievably gifted, genius Master-level developers, honed by the continual mutual improvement of the review process. However, people with such exospheric skills (a layer of the atmosphere named, I believe, after exarkun's brain) get tired of answering simple, repetitive questions from impatient and confused novices. This is a good problem to have, but it's still a problem. If you know some things about Twisted but you're not really an expert yet, you should really help others learn by answering questions on this list and on IRC. It would decrease the pressure on people whose time would be better spent answering the really, really hard questions, or better yet fixing bugs so that the hard questions won't even come up.
IIRC, at the time Twisted Python was created, thread support in Python was simply awful. Threads were absolutely not a solution for dealing with multiple client connections to a server application, and the only alternative was asyncore.
I don't think that Python's thread support was that awful, nor that it has changed that much since then. Are you referring to the GIL? Anyway, if you are, let's not talk about this any more.
As many of you may remember, asyncore was not great, but it *was* simple. Writing an asyncore application required knowledge of maybe three different classes, so while you were working on understanding asynchronous networking, you didn't have to deal with learning a vast new API.
Twisted is actually simpler than asyncore by a fair margin. Compare a Twisted echo server to an asyncore echoserver. Twisted has _more stuff in it_ than Asyncore does, but it is a lot easier to use, as well as more portable, for the application programmer. (You still need to know about WSA errors on Windows if you want to use asyncore, for example.)
The problem I've seen with various responses from seasoned Twisted devs to unexperienced developers is that one can only explain why you don't want to use any kind of long-blocking call so many times. After that, answers start becoming glib and/or overly terse, but I can't really blame anyone for that.
This is the problem I mentioned above.
I definitely agree with you about the state of Twisted.Web. I think the culprit here is not entirely a shortage of documentation. The real problem is Web2. <snip blah blah blah web web2 confusion etc>
We talked a lot about this at PyCon. I don't want to bury the resolution here, in the middle of a thread that a lot of people have probably already killfiled, but this problem _is_ recognized as a priority and _is_ getting solved, thanks in large part to the renewed efforts of David Reid, James Knight, and Wilfredo Sanchez. I'll try to scream it from the rooftops as soon as I can.
I have to say, I still don't really know what AMP is, and I've asked a bunch of times. Maybe I actually do know, by now, but I've certainly forgotten.
First google hit for "twisted amp": http://twistedmatrix.com/documents/current/api/twisted.protocols.amp.html Perhaps there should be more documentation, but I think that's a good introductory explanation.
I really think that doing this properly requires a core team of people at least as large as the core Twisted dev group. They would need to have both a knack for documentation and an understanding of somewhat low-level networking concepts, *and* an ability to read source code effectively.
Absolutely. But - an important note - these people DO NOT need to be deep Twisted wizards on the level of JP, me, Chris Armstrong or whoever; they can just have a passing familiarity with the concepts and the capacity to ask and answer questions when necessary.
Now, I don't mean to point out obstacles and say it's hopeless, but I think this relates to the critical mass I was talking about earlier. I think Twisted just needs to reach that level where there's enough people who want to write documentation that it gets done.
One of the things I did at PyCon was to reach out to the Django community and ask them to start considering what it would take for Twisted to be the preferred container and deployment platform for Django. They're thinking about it. I hope we can keep that dialogue going. Supporting other Python frameworks (especially web frameworks) would provide us with a much broader audience of people with a different skill set. Unfortunately 99% of those people will have zero interest in asynchronous networking, but, for example, "twistd" as a command line tool is kind of neat. There are lots of ways we can suck them in and interest them in the wider Twisted universe outside of just web. Bottom line, though: those are the people who can make our website look great, who can organize our documentation, etc. It's no secret that I'm not a fan of Django's technological architecture but I think their documentation is _fantastic_; easily twice as good as ours, probably more like ten times as good in certain areas.
Other attempts to force the issue haven't really met with much success; I know there used to be (perhaps still are) a few bounties out there on documentation, but not much has happened in that arena since then. (Personally, I am anti-bounty, as I feel -- perhaps irrationally so -- that it cheapens the hours and hours of work that people have done for free.)
Whatever the reason, you're right: bounties never really worked. Divmod is going to be doing a bunch of consulting for the TSF, but that paid development isn't going to be on the basis of a ticket-by-ticket basis, and bounties are not a good way to recognize or compensate contributors.
I think the best way for us to address this in the short term is to really try to focus on group documentation. The current Trac wiki can barely be called collaborative; as a start why not transfer the Twisted docs into the wiki, and allow Trac users to modify and update this information?
Because the version control system used by trac is broken. Because trac's wiki syntax is a custom hack which we have no other tools to work with. Because users who know even the tiniest smattering of HTML can submit patches against the existing documentation. Because dealing with spam in trac is a huge hassle. Because trac's wiki isn't included in the release. Because the tools don't exist *to* include trac's wiki in the release. Because it's a huge project which would take many man- months to do nothing but put our documentation into an inferior format. I could go on. Maybe you could write a tool which would automatically allow users to edit the lore documentation and generate patches / file tickets for reviewing those patches? That would be pretty awesome.
Furthermore, considering the length some of the posts I see here, I'd like to suggest that if you're going to spend 30 minutes writing an email explaining some concept, why not write a mini tutorial about it instead?
Writing a tutorial is a lot harder than writing an email.
Even if you just copy and paste the email you were going to send into the wiki, it's still a start, and others can work on it from there.
*this* kind of ad-hoc stuff is what should be on a wiki. But it should be moving in the direction of the real docs, not away from them. I hope this was illustrative, if not quite worthy of being a tutorial :).
Glenn H Tarbox wrote:
(yet this same group complains that Git is too complex to be used for source code control... even though its core architecture eclipses the alternatives being used and considered...)
Seeing Pythonistas using git saddens me a little. Mercurial is git done right. -- Nicola Larosa - http://www.tekNico.net/ Not only is Vista + Office the most bloated desktop software stack ever to emerge from Redmond, its system requirements are so out of proportion with recent hardware trends that only the latest and greatest from Intel or AMD can support its epically porcine girth. -- exo.blog research staff, November 2007
On Thu, Mar 20, 2008 at 4:56 PM, Nicola Larosa <nico@teknico.net> wrote:
Glenn H Tarbox wrote:
(yet this same group complains that Git is too complex to be used for source code control... even though its core architecture eclipses the alternatives being used and considered...)
Seeing Pythonistas using git saddens me a little.
Mercurial is git done right.
Really? I've heard the same about Canonical's Bazaar...also written in python...
On Fri, Mar 21, 2008 at 12:52 PM, John Wells <lists@sourceillustrated.com> wrote:
On Thu, Mar 20, 2008 at 4:56 PM, Nicola Larosa <nico@teknico.net> wrote:
Glenn H Tarbox wrote:
(yet this same group complains that Git is too complex to be used for source code control... even though its core architecture eclipses the alternatives being used and considered...)
Seeing Pythonistas using git saddens me a little.
Mercurial is git done right.
Really? I've heard the same about Canonical's Bazaar...also written in python...
Except Bazaar isn't git done right, it's distributed version control done right. jml
Jonathan Lange wrote:
On Fri, Mar 21, 2008 at 12:52 PM, John Wells <lists@sourceillustrated.com> wrote:
On Thu, Mar 20, 2008 at 4:56 PM, Nicola Larosa <nico@teknico.net> wrote:
Glenn H Tarbox wrote:
(yet this same group complains that Git is too complex to be used for source code control... even though its core architecture eclipses the alternatives being used and considered...)
Seeing Pythonistas using git saddens me a little.
Mercurial is git done right.
Really? I've heard the same about Canonical's Bazaar...also written in python...
Except Bazaar isn't git done right, it's distributed version control done right.
OT! Please keep VCS wars/opinionating off the twisted list. Steve
Nicola Larosa wrote:
Mercurial is git done right.
Really? I've heard the same about Canonical's Bazaar...also written in python...
If you mean that Mercurial is BazaarNG done right, yes, definitely. ;-) BazaarNG has better integration with Subversion than Mercurial (currently). On the other hand, it's not as fast as Mercurial, but mainly, it's not as *simple* as Mercurial. Canonical deciding to rewrite bzr, instead of backing Mercurial, has been a loss for the Python community. -- Nicola Larosa - http://www.tekNico.net/ It hurts a bit to hear someone you really love relating or demonstrating delight received from another lover. But when you get past this, it's utterly liberating, as if you have finally ridded yourself of the worst vestige of our current society's terrible scarcity of love. -- Dave Pollard, November 2007
Please stop. On 06:35 am, nico@teknico.net wrote:
Nicola Larosa wrote:
It is allowed on all hands, that the primitive way of breaking eggs, before we eat them, was upon the larger end; but his present majesty 19s grandfather, while he was a boy, going to eat an egg, and breaking it according to the ancient practice, happened to cut one of his fingers.
his present majesty 19s grandfather, while he was a boy, going to eat an egg, and breaking it according to the ancient practice, happened to cut one of his fingers.
Long live the most puissant king of Lilliput! all true believers break their eggs at the convenient end. -- Nicola Larosa - http://www.tekNico.net/
It hurts a bit to hear someone you really love relating or demonstrating delight received from another lover. But when you get past this, it's utterly liberating, as if you have finally ridded yourself of the worst vestige of our current society's terrible scarcity of love. -- Dave Pollard, November 2007
_______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
glyph@divmod.com wrote:
Please stop.
Ok, I will, but...
On 06:35 am, nico@teknico.net wrote:
Nicola Larosa wrote:
..no, I didn't! Whose is this stuff? Not mine. Glyph, if this is your frolicsome way of implying that what I said was irrelevant, well, point taken. :-) Otherwise, I'm puzzled.
It is allowed on all hands, that the primitive way of breaking eggs, before we eat them, was upon the larger end; but his present majesty 19s grandfather, while he was a boy, going to eat an egg, and breaking it according to the ancient practice, happened to cut one of his fingers.
his present majesty 19s grandfather, while he was a boy, going to eat an egg, and breaking it according to the ancient practice, happened to cut one of his fingers.
Long live the most puissant king of Lilliput! all true believers break their eggs at the convenient end.
-- Nicola Larosa - http://www.tekNico.net/
On 09:05 am, nico@teknico.net wrote:
Glyph, if this is your frolicsome way of implying that what I said was irrelevant, well, point taken. :-) Otherwise, I'm puzzled.
I guess if you didn't get the joke, others might not either... Those were passages taken from Gulliver's Travels related to the big- endian vs. little-endian debate, a meaningless conflict between essentially identical societies that lead to decades of war.
On Fri, Mar 21, 2008 at 5:17 AM, <glyph@divmod.com> wrote:
On 09:05 am, nico@teknico.net wrote:
Glyph, if this is your frolicsome way of implying that what I said was irrelevant, well, point taken. :-) Otherwise, I'm puzzled.
I guess if you didn't get the joke, others might not either...
Those were passages taken from Gulliver's Travels related to the big- endian vs. little-endian debate, a meaningless conflict between essentially identical societies that lead to decades of war.
Is there a python-flamewars mailing list? That would be really great, so everyone could argue about setuptools, web frameworks, concurrency models, revision control ... I think it might help extend our lifespans as well.
Long live the most puissant king of Lilliput! all true believers break their eggs at the convenient end.
Now that you mention eggs ... -- \\\\\/\"/\\\\\\\\\\\ \\\\/ // //\/\\\\\\\ \\\/ \\// /\ \/\\\\ \\/ /\/ / /\/ /\ \\\ \/ / /\/ /\ /\\\ \\ / /\\\ /\\\ \\\\\/\ \/\\\\\/\\\\\/\\\\\\ d.p.s
On Thu, Mar 20, 2008 at 9:36 AM, Glenn H Tarbox, PhD <glenn@tarbox.org> wrote:
On Thu, 2008-03-20 at 07:33 -0400, Steve Holden wrote:
glyph@divmod.com wrote: As I believe I mentioned early on, one of the issues is that the Twisted core developers are so smart (I believe I may have used the phrase "brains the size of planets"), and so knowledgeable about Twisted, that it's difficult sometimes to get a 90% answer out of them. This was particularly the case with Itamar, whom I lambasted quite mercilessly (and whom I therefore owe a public apology: sorry, Itamar) when he tried to complete all the corner cases after a slightly inaccurate statement on my part that was perfectly good enough for a learner.
There is a great deal of anecdotal evidence that great players make poor coaches.
One of the biggest (glaring?) issues with Twisted is the abysmal state of the documentation (none) making the code the best source... and history is replete with the massive successes that approach has borne...
I disagree with this evaluation. While parts of Twisted could be better documented, overall, it is pretty darn good for an open source project that addresses a problem as difficult as asynchronous networking. How many open source projects have a book?
What documentation there is includes: "If you need to call a method that returns a deferred within your callback chain, just return that deferred, and the result of the secondary deferred's processing chain will become the result that gets passed to the next callback of the primary deferreds processing chain"
Now, the above is true and clear to those of us who know twisted... but I've used that quote for levity... its simply incomprehensible... but absolutely critical to understanding the power of twisted. I'd say that the current state of twisted documentation is in part represented by that quote... and much of the reason twisted gets thrown out early as an option.
Asynchronous networking is simply hard. And Twisted has a very sophisticated take on it. Saying the problem is the documentation is like someone saying "quantum mechanics is poorly documented...all that talk about Hilbert spaces, eigenstates and superposition..." It is not poorly documented, it is simply hard and conceptually challenging. Also, I think the proof is in the pudding. Most people who really need Twisted for their projects _are_ in fact able to learn it (for the most part without reading the source code). The documentation can't be that bad. Doesn't mean there is not room for improvement though. Brian
On 20 Mar, 09:28 pm, ellisonbg.net@gmail.com wrote:
Also, I think the proof is in the pudding. Most people who really need Twisted for their projects _are_ in fact able to learn it (for the most part without reading the source code). The documentation can't be that bad. Doesn't mean there is not room for improvement though.
Although I believe we have a long way to go, I appreciate the fact that in this round, it's not the authors of the documentation, but members of the community who have actually read it who are coming to its defense. Thanks. It's useful to hear the criticism, but it's energizing to hear the praise :).
One of the biggest (glaring?) issues with Twisted is the abysmal state of the documentation (none) making the code the best source... and history is replete with the massive successes that approach has borne...
I disagree with this evaluation. ...
Likewise.
Asynchronous networking is simply hard. And Twisted has a very sophisticated take on it. Saying the problem is the documentation is like someone saying "quantum mechanics is poorly documented...all that talk about Hilbert spaces, eigenstates and superposition..." It is not poorly documented, it is simply hard and conceptually challenging.
Also, I think the proof is in the pudding. Most people who really need Twisted for their projects _are_ in fact able to learn it (for the most part without reading the source code). The documentation can't be that bad. Doesn't mean there is not room for improvement though.
I totally agree with that. I'm a reasonably bright chap, but I'm not Einstein. I get Twisted, and I got it quickly enough and well enough to (I think) do some pretty damn sophisticated things. (I did have the benefit of having already tried a threaded approach and seen how disastrous it was...)
Brian
_______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
Phil Mayers wrote: [...]
Also, I think the proof is in the pudding. Most people who really need Twisted for their projects _are_ in fact able to learn it (for the most part without reading the source code). The documentation can't be that bad. Doesn't mean there is not room for improvement though.
I totally agree with that. I'm a reasonably bright chap, but I'm not Einstein. I get Twisted, and I got it quickly enough and well enough to (I think) do some pretty damn sophisticated things.
It *has& improved a lot.
(I did have the benefit of having already tried a threaded approach and seen how disastrous it was...)
I've actually used threads to send emails in parallel (200-500 at a time), but if I'd known how to use Twisted it would almost certainly have been easier to get running and debug. I'm probably one of those people who will shy away from something that isn't immediately approachable. Perhaps all that's really needed is a ring of newbie-friendly stuff to make sense of the existing documentation? That, and a re-write of certain head-twisting paragraphs ... regards Steve
On Thu, 2008-03-20 at 07:33 -0400, Steve Holden wrote:
glyph@divmod.com wrote:
I left the session feeling we had accomplished hardly anything, but was persuaded afterwards that wasn't the case.
One of the tragedies of the session was due to the blue screen crash of my own computer I have absolutely nothing left of the code we developed. I had hopes that one or two blog entries might appear to allow me to lift it from those attending, but so far the success of the session is a closely guarded secret among PyCon attendees (thought it's been gratifying to have people saying "I wished I'd gone to that").
If someone can provide me with the code I will undertake to produce some sort of blog entry, and this might further publicize Twisted. Never underestimate the value of marketing: the Twisted community is a subset of the Python community, and it's my particular vanity that PyCon has helped to increase the Python community. It's important to keep feeding introductory material into the process as growth continues, because typically 50% of those present are likely to be newbies.
Having contributed the replacement laptop, I've got the "official" working code from Teach Me Twisted. I'd be happy to send it to you, Steve, or anyone else who wants to blog on the session. One caveat: the laptop I had with me at python belongs to my employer, so it's sitting in my office right now, and I won't be able to get to it until Monday.
Next year, we should definitely have more regular Twisted talks; I'd say that someone else should do another "teach me twisted" session, but I don't know if anyone else has the raw charisma and pedagogical expertise that Mr. Holden combined with Twisted ignorance to make this session so great :).
Don't forget the whisky ...
Believe me, I won't. ;) Actually I think the whisky was a minor but essential ingredient in making the event as fantastic as it was. Just having the bottle sitting up front was a good reminder to people that we were there because we think this stuff is fun. It took a lot of the formality off of the learning process, and that informality helped people get excited about the endeavor.
What we possibly need first of all is for someone to do a "Teach Me Teach Me" in the tutorial track, with myself and a number of the more experienced trainer types as the "subject matter experts". These things are always one-off in nature and it's unrealistic to expect that they will all have the same charm as "Teach Me Twisted" did this year for all the reasons I mention above, but if it gets information out more effectively about "difficult" topics it's probably worth a try if we can find someone to facilitate them.
I'd love to try my hand at "teach me" style teaching, for what it's worth, and would be interested in a Teach Me Teach Me session.
regards Steve
J. Clifford Dyer wrote:
On Thu, 2008-03-20 at 07:33 -0400, Steve Holden wrote: [...]
If someone can provide me with the code I will undertake to produce some sort of blog entry, and this might further publicize Twisted. Never underestimate the value of marketing: the Twisted community is a subset of the Python community, and it's my particular vanity that PyCon has helped to increase the Python community. It's important to keep feeding introductory material into the process as growth continues, because typically 50% of those present are likely to be newbies.
Having contributed the replacement laptop, I've got the "official" working code from Teach Me Twisted. I'd be happy to send it to you, Steve, or anyone else who wants to blog on the session. One caveat: the laptop I had with me at python belongs to my employer, so it's sitting in my office right now, and I won't be able to get to it until Monday.
The authentic source would be very welcome, Cliff, and thanks. Hope the new laptop is behaving itself ...
Next year, we should definitely have more regular Twisted talks; I'd say that someone else should do another "teach me twisted" session, but I don't know if anyone else has the raw charisma and pedagogical expertise that Mr. Holden combined with Twisted ignorance to make this session so great :).
Don't forget the whisky ...
Believe me, I won't. ;) Actually I think the whisky was a minor but essential ingredient in making the event as fantastic as it was. Just having the bottle sitting up front was a good reminder to people that we were there because we think this stuff is fun. It took a lot of the formality off of the learning process, and that informality helped people get excited about the endeavor.
What we possibly need first of all is for someone to do a "Teach Me Teach Me" in the tutorial track, with myself and a number of the more experienced trainer types as the "subject matter experts". These things are always one-off in nature and it's unrealistic to expect that they will all have the same charm as "Teach Me Twisted" did this year for all the reasons I mention above, but if it gets information out more effectively about "difficult" topics it's probably worth a try if we can find someone to facilitate them.
I'd love to try my hand at "teach me" style teaching, for what it's worth, and would be interested in a Teach Me Teach Me session.
Maybe you could facilitate it? regards Steve
On Fri, 2008-03-21 at 16:05 -0400, Steve Holden wrote:
What we possibly need first of all is for someone to do a "Teach Me Teach Me" in the tutorial track, with myself and a number of the more experienced trainer types as the "subject matter experts". These things are always one-off in nature and it's unrealistic to expect that they will all have the same charm as "Teach Me Twisted" did this year for all the reasons I mention above, but if it gets information out more effectively about "difficult" topics it's probably worth a try if we can find someone to facilitate them.
I'd love to try my hand at "teach me" style teaching, for what it's worth, and would be interested in a Teach Me Teach Me session.
Maybe you could facilitate it?
regards Steve
Sounds like fun. I'll think about it.
_______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
participants (15)
-
Brian Granger -
Drew Smathers -
Duncan McGreggor -
Glenn H Tarbox, PhD -
glyph＠divmod.com -
J. Clifford Dyer -
John Wells -
Jonathan Lange -
L. Daniel Burr -
Maarten ter Huurne -
Nicola Larosa -
Phil Christensen -
Phil Mayers -
Stephen Waterbury -
Steve Holden