[Twisted-Python] The problem with Twisted...
... is that we have no word for "entrepreneur". Just had a conversation with a guy on #python, and he raised some valid points. He appeared to be a programmer, and his concerns were focussed on his job, and on pitching Twisted to mgmt. Firstly, his biggest concern was documentation. He said that he doesn't want to trawl through Twisted's source code to figure things out. These days, (most of the time) you don't have to do that, but occasionally you do. Of course, our code is generally quite readable (except for the odd module here and there). Suggestions: * API docs Ask ten Java developers what they like most about Java, and nine will say "the API docs". I humbly suggest that we should get better at writing these. * Howtos I remain somewhat unconvinced that the best way to write a book is to present a series of HOWTOs. But then, I also reckon that most of what we call HOWTOs, aren't. Secondly, he couldn't find any information on the twistedmatrix.com website that said "Managers, this is why you should use Twisted". I hate writing that sort of thing, but I imagine it needs to be done. It could call cred an "Identity Server" and things like that. It could also not use "asynchronous" as selling point. Managers want to hear words they've already heard. They want to hear why Twisted isn't just something cobbled together by a bunch of geeks in their bedrooms. The Java website starts off with a page geared entirely towards management (even if the headings don't say so), with all the useful programmer stuff hidden away from view. Would it be a stupid idea to have: - http://www.twistedmatrix.com/ : Twisted, the Framework of your Internet - http://www.twistedmatrix.com/dev/ : You have been sucked into the vortex. ?? Or even dispense with a site that targets developers entirely, except for a "This is why Twisted's technology is cool" page. After all, the grunts will be happy with doco, and coders who want more than that will find it on the list and the channel. Thirdly, we should really, really, really get Coil done. This guy didn't mention it, but I know many people (good programmers, even) who feel uncomfortable at a command line, and much prefer web-based (or Windows-based) administration. One of the cool things about Twisted is that it's extremely easy to start a server for just about anything on your personal PC. This would be made much more obvious with a GUI like Coil. Now, all this is suggested humbly and tentatively. I'm not sure whether any of these things are good things. I do know that they'd make ppl who I've worked with in corporate environments more comfortable. (and not just the muppets) I'm very interested in discussion, and what you all think of this. Also, I hope this email isn't critical in a vague way, and isn't inflammatory. It's not meant that way, rather it's meant to note problems that other people see and have told me, and to suggest ways of solving them. cheers, jml
On Thu, 2003-06-05 at 14:45, jml@ids.org.au wrote:
... is that we have no word for "entrepreneur".
Especially the website which seems really designed by and for developpers (is it bad ?).
Firstly, his biggest concern was documentation. He said that he doesn't want to trawl through Twisted's source code to figure things out. These days, (most of the time) you don't have to do that, but occasionally you do. Of course, our code is generally quite readable (except for the odd module here and there).
Suggestions: * API docs Ask ten Java developers what they like most about Java, and nine will say "the API docs". I humbly suggest that we should get better at writing these.
I'am quite happy with the API but some method & params really need more doc.
* Howtos I remain somewhat unconvinced that the best way to write a book is to present a series of HOWTOs. But then, I also reckon that most of what we call HOWTOs, aren't.
I think howtos have to be reorganized. It's pretty hard to get started with twisted. Moreover, I'am trying to make an application with woven, and have difficulties with documentation on it. Maybe we need more exemples.
Secondly, he couldn't find any information on the twistedmatrix.com website that said "Managers, this is why you should use Twisted". I hate writing that sort of thing, but I imagine it needs to be done. It could call cred an "Identity Server" and things like that. It could also not use "asynchronous" as selling point. Managers want to hear words they've already heard. They want to hear why Twisted isn't just something cobbled together by a bunch of geeks in their bedrooms.
It would be great. I'm also a manager, and have to convince also my clients that twisted is good choice for us.
On Thu, Jun 05, 2003 at 09:10:38AM +0200, Philippe Lafoucri?re wrote:
I think howtos have to be reorganized. It's pretty hard to get started with twisted. Moreover, I'am trying to make an application with woven, and have difficulties with documentation on it. Maybe we need more exemples.
Just a brief note: The Woven docs are new, so any suggestions to improve them are extremely welcome! -Andrew.
On Thu, 2003-06-05 at 09:22, Andrew Bennetts wrote:
On Thu, Jun 05, 2003 at 09:10:38AM +0200, Philippe Lafoucri?re wrote:
I think howtos have to be reorganized. It's pretty hard to get started with twisted. Moreover, I'am trying to make an application with woven, and have difficulties with documentation on it. Maybe we need more exemples.
Just a brief note: The Woven docs are new, so any suggestions to improve them are extremely welcome!
-Andrew.
I'll give you my feedback when I finish reading it. _______________________________________________
Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python -- Philippe Lafoucrière <lafou@wanadoo.fr> InFuzzion
On Thu, Jun 05, 2003 at 10:39:09AM +0200, Philippe Lafoucri?re wrote:
I'll give you my feedback when I finish reading it.
Ok, retain all doc in memory is hard. I don't see the difference between wvfactory_ and wvupdate_ ?
I'm no Woven expert, but wvupdate_ is described here: http://twistedmatrix.com/documents/howto/viewindepth#auto5 I presume you're saying that's not clear enough? (I really should try to learn Woven myself sometime, so I can know how you feel... :) -Andrew.
I'm no Woven expert, but wvupdate_ is described here: http://twistedmatrix.com/documents/howto/viewindepth#auto5
I presume you're saying that's not clear enough?
(I really should try to learn Woven myself sometime, so I can know how you feel... :)
Yes, Please try it. I a twisted newbie, but sometimes things happen magically. I knew the page howto/viewindepth#auto5 (red all the doc already) but this is not clear enough for me (maybe it's because I'm not english fluent). For me, wvupdate_ and wvfactory_ are used to create a new View for a page.Page. In exemples : ----------------------------------------------------------------- class MyPage(page.Page): def wvupdate_foo(self, request, widget, data): if data > 10: newNode = widget.getPattern("large") else: newNode = widget.getPattern("small") newNode.appendChild(request.d.createTextNode(str(data))) widget.appendChild(newNode) ----------------------------------------------------------------- class MyView(view.View): def generate(self, request, node, model): return request.d.createTextNode("Hello, world!") class MyPage(page.Page): def wvfactory_foo(self, request, node, model): return MyView(model) ----------------------------------------------------------------- I think I can put : **** if data > 10: newNode = widget.getPattern("large") else: newNode = widget.getPattern("small") newNode.appendChild(request.d.createTextNode(str(data))) widget.appendChild(newNode) **** in the wvfactory_foo !? ================================================================== By the way, I was looking for documentation on cred, since I want to persist identies created on a twisted server. The cred howto needs some rewrite with concrete exemples. I can't pickle identities with Shelf since Indenties have references to Auth, and Auth to Identities (infinite loop when pickeling). -- Philippe Lafoucrière <lafou@wanadoo.fr> InFuzzion
On Thu, Jun 05, 2003 at 11:28:06AM +0200, Philippe Lafoucri?re wrote: [...]
I think I can put : **** if data > 10: newNode = widget.getPattern("large") else: newNode = widget.getPattern("small") newNode.appendChild(request.d.createTextNode(str(data))) widget.appendChild(newNode) **** in the wvfactory_foo !?
But wvfactory_foo's third argument is a DOM node, not a generic Widget. There is no 'widget' in a wvfactory_. -Andrew.
But wvfactory_foo's third argument is a DOM node, not a generic Widget. There is no 'widget' in a wvfactory_.
ho ok, haven't seen that. In pilePicture tutorial, in ImageDisplay class : def wchild_preview(self, request): return static.File(self.image) "static" comes from nowhere.
_______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python -- Philippe Lafoucrière <lafou@wanadoo.fr> InFuzzion
On Thu, Jun 05, 2003 at 01:42:28PM +0200, Philippe Lafoucri?re wrote:
But wvfactory_foo's third argument is a DOM node, not a generic Widget. There is no 'widget' in a wvfactory_.
ho ok, haven't seen that.
This difference is mentioned under the "wvupdate_" heading of doc/howto/viewindepth.
In pilePicture tutorial, in ImageDisplay class :
def wchild_preview(self, request): return static.File(self.image)
"static" comes from nowhere.
It comes from this import line: from twisted.web import server, static -Andrew.
On Thursday, June 5, 2003, at 02:28 AM, Philippe Lafoucrière wrote:
I think I can put :
*snip*
in the wvfactory_foo !?
You can, but you should not. Factory methods have one purpose and one purpose only: To return a new object. Update methods are special because they allow you to write the equivalent of a new Widget class with an overridden setUp method, without writing a new class. Why does it matter so much where the DOM manipulation occurs? Because one of the design goals of woven was to allow a portion of an already-rendered page to be re-rendered. The way this is currently implemented is by keeping the Widget instances produced by the wvfactory_ methods in memory so that the generate (and thus setUp) methods may be executed again multiple times. How is wvupdate_ different? When woven notices a wvupdate_ method, it creates a generic Widget instance and places a function pointer to the wvupdate_ method on this instance. In this way, the wvupdate_ method can be executed multiple times in order to re-render that portion of the page. I know it is confusing, and I hope to remove some of this complexity in a future woven version. dp
You can, but you should not. Factory methods have one purpose and one purpose only: To return a new object.
Update methods are special because they allow you to write the equivalent of a new Widget class with an overridden setUp method, without writing a new class.
Why does it matter so much where the DOM manipulation occurs? Because one of the design goals of woven was to allow a portion of an already-rendered page to be re-rendered. The way this is currently implemented is by keeping the Widget instances produced by the wvfactory_ methods in memory so that the generate (and thus setUp) methods may be executed again multiple times.
How is wvupdate_ different? When woven notices a wvupdate_ method, it creates a generic Widget instance and places a function pointer to the wvupdate_ method on this instance. In this way, the wvupdate_ method can be executed multiple times in order to re-render that portion of the page.
I know it is confusing, and I hope to remove some of this complexity in a future woven version.
dp
Thank you for this clear explanation ! I understand now !
On Thu, Jun 05, 2003 at 05:22:54PM +1000, Andrew Bennetts wrote:
On Thu, Jun 05, 2003 at 09:10:38AM +0200, Philippe Lafoucri?re wrote:
I think howtos have to be reorganized. It's pretty hard to get started with twisted. Moreover, I'am trying to make an application with woven, and have difficulties with documentation on it. Maybe we need more exemples.
Just a brief note: The Woven docs are new, so any suggestions to improve them are extremely welcome!
One thing I found confusing when reading the Woven docs: In the PicturePile walkthrough, there's a section dealing with storing data in a session variable. Basically it defines two empty classes and tells Twisted they can be used to deal with Session objects. This seemed (not so) subtly bizzare, so I read the components-and- adapters introduction, which led me to believe that there would be all sorts of clever magic in the Session object to deal with this sort of thing. So I trundled over to the Session class in the API docs to see how the Session object is *supposed* to be used, rather than a cheating short-cut way. The Session API docs say "This utility class contains no functionality, but is used to represent a session." The Session class doesn't appear to inhert from anything that actually contains session-related functionality, and the adapter classes sure don't contain session-related functionality, so I have no idea where sessiony stuff is done, or how to do it in my own programs, or anything clever that I might do. In ASP, admittedly based on a much stupider language, the Session object is effectively a dictionary. It's much simpler to understand. I assume there's useful things the Twisted session object can do that you can't do in ASP, but I'm not very clear on what those things might be. -- ___________ ____________________________ | Screwtape | Reply-To: munged on Usenet |________ ______ ____ __ _ _ _ | | "You seem cool for a naked chick in a booth - let's be pals someday." -- PUSA |
screwtape@froup.com writes:
The Session class doesn't appear to inhert from anything that actually
contains session-related functionality, and the adapter classes sure don't contain session-related functionality, so I have no idea where sessiony stuff is done, or how to do it in my own programs, or anything clever that I might do.
In ASP, admittedly based on a much stupider language, the Session object is effectively a dictionary. It's much simpler to understand. I
assume there's useful things the Twisted session object can do that you can't do in ASP, but I'm not very clear on what those things might
be.
I am a newbie to Woven, but I just used the session like this and it seemed to work fine. Just like in asp you can use it to store you own data, but instead of being limitited to primitive datatypes like in ASP you use your own classes like in the example below. ... Some Page derived class def getChild(self, postpath, request): if request.method == 'POST': session = request.getSession() session.user = User(request.args['user'][0], request.args['password'][0]) session.user.logIn() if session.user.isLoggedIn(): return Redirect('../projectorder') .... -- Vennlig hilsen Syver Enstad
On Thu, Jun 05, 2003 at 10:45:31PM +1000, jml@ids.org.au wrote:
... is that we have no word for "entrepreneur".
Summary: Twisted is scary to people with money. We can make it less scary. 1. Docs. a) We need more docs, esp API docs. This needs to be a commitment to docs, and not just a writing binge. b) A book is more than a collection of howtos 2. The website should target "decision makers" primarily. Hackers only need links to download, docs, mailing list, and why our tech is cool 3. Coil. Not a flame. Not claiming amazing ideas. Just stuff to make ppl feel more warm and fuzzy. cheers, jml
jml@ids.org.au wrote:
On Thu, Jun 05, 2003 at 10:45:31PM +1000, jml@ids.org.au wrote:
... is that we have no word for "entrepreneur".
Summary: Twisted is scary to people with money. We can make it less scary. 1. Docs. a) We need more docs, esp API docs. This needs to be a commitment to docs, and not just a writing binge. b) A book is more than a collection of howtos
As a manager, I more or less have to agree, even though I've defended Twisted's docs on c.l.p from time to time. They certainly could be better, and I do agree that the API doc areas could stand some improvements. What I really ought to do is start noting the fact each time we encounter a less than useful description, and maybe even try to improve it once we figure it out.
2. The website should target "decision makers" primarily. Hackers only need links to download, docs, mailing list, and why our tech is cool
You might think about what _kind_ of decision maker you wish to target. Do you definitely want to target all kinds? Targetting those with an adequate understanding of agile development, the value of Python, etc, should be pretty easy. Hardly need to spend more than a passing word or two to catch them... it's the more traditional types, used to using certain other technologies, who might be harder. How do you target a Java head, and more interestingly: why would you? (Yes, I understand the mandate for world domination, but aside from that? ;-))
3. Coil.
I have only one thing to say in this area, which is please don't anyone think about developing this just because you think you need to in order to help convince someone to use Twisted. If you don't need it enough to do it for yourself or for someone who has specific documented needs (a.k.a. "user stories") you will not produce something useful to anyone and you'll waste your time to boot. -Peter
On Wed, Jun 04, 2003 at 10:15:01PM -0400, Peter Hansen wrote:
jml@ids.org.au wrote:
3. Coil.
I have only one thing to say in this area, which is please don't anyone think about developing this just because you think you need to in order to help convince someone to use Twisted. If you don't need it enough to do it for yourself or for someone who has specific documented needs (a.k.a. "user stories") you will not produce something useful to anyone and you'll waste your time to boot.
I've seen the old coil, and heard discussion on what the new coil will do, and I'm sufficiently excited to believe it's *very* worthwhile... So, Donovan, what happened to the code you were going to post to the list yesterday? :) Anyway, back to Peter's advice -- you have a point. But couldn't the same argument apply to making a manager-friendly web site? I'm somewhat inclined to simply keeping good code, and rely on the quality to eventually speak for itself, rather than expending effort on a perceived need to market Twisted to non-technical people. (Of course, if marketing Twisted is someone's itch, they should be welcome to scratch it!) On the other hand, I think more and better docs for developers (i.e. the APIs and "HOWTO"s, which are misnamed I think) is definitely worthwhile. The more developers we can attract, the better tested our designs and implementation will be, and the better quality our project will become. At the moment, the docs are still somewhat of a barrier to new developers, but thankfully not the insurmountable hurdle they used to be :) Basically, if I had a choice between spending time on improving docstrings or writing manager-friendly prose, I'd choose to write docstrings. Oh! And don't forget, we have some *excellent* marketing material already: the 1.0 Press Release, linked from the front page. -Andrew.
Andrew Bennetts wrote:
On Wed, Jun 04, 2003 at 10:15:01PM -0400, Peter Hansen wrote:
I have only one thing to say in this area, which is please don't anyone think about developing this just because you think you need to in order to help convince someone to use Twisted. If you don't need it enough to do it for yourself or for someone who has specific documented needs (a.k.a. "user stories") you will not produce something useful to anyone and you'll waste your time to boot.
I've seen the old coil, and heard discussion on what the new coil will do, and I'm sufficiently excited to believe it's *very* worthwhile...
Anyway, back to Peter's advice -- you have a point. But couldn't the same argument apply to making a manager-friendly web site? I'm somewhat inclined to simply keeping good code, and rely on the quality to eventually speak for itself, rather than expending effort on a perceived need to market Twisted to non-technical people. (Of course, if marketing Twisted is someone's itch, they should be welcome to scratch it!)
Very true on all points! Of course, marketing XP style should not involve a whole lot of upfront packaging and cosmetics, but should be driven by actual need. After all, real marketing, the heart of what the very word is supposed to mean as opposed to how its misused and abused by all the glossy brochure types in the word, is _understanding customer needs and developing products which fulfill them_. So if marketing Twisted is someone's itch, and they want to be most effective, they should, IMHO, go step by step XP style and try to understand what the world needs in one particular area of Twisted (say, coil) based on real-world information: ask around, write proposals and respond to feedback, and most important of all: develop prototypes (quick and somewhat dirty) to elicit direct feedback on what will actually work. Basically, in my mind, there is no reason to distinguish between marketing and "traditional" XP development, as both should look the same if one is doing them most effectively. Of course, if by "marketing Twisted" you meant someone actually wants to do the glossy brochure thing on the product, like souping up the web site and writing intros for managers, I'm not sure I have much advice except I don't think it's such a good idea. :-)
On the other hand, I think more and better docs for developers (i.e. the APIs and "HOWTO"s, which are misnamed I think) is definitely worthwhile. The more developers we can attract, the better tested our designs and implementation will be, and the better quality our project will become.
Yes. Yes, yes, yes. YES! That goes back to my original "what kind of manager are you targeting" question. The best kind to attract is the kind who will already be attracted by your approach, and by the quality of the product you are delivering. Those things speak for themselves and don't need the glossy brochure kind of "marketing", which is really about selling inferior products to unsophisticated customers. (Again, though, if that's what you want to spend your time doing, I guess nobody should be trying to stop you. ;-) (Somewhat rambling, but it's very early in the morning and I didn't get enough sleep... forgive me.) -Peter
On Thursday, June 5, 2003, at 07:53 AM, Peter Hansen wrote:
Basically, in my mind, there is no reason to distinguish between marketing and "traditional" XP development, as both should look the same if one is doing them most effectively.
Somehow, I feel as though the God of Ethical and Intelligent Marketing Practices is posting to this mailing list.
Of course, if by "marketing Twisted" you meant someone actually wants to do the glossy brochure thing on the product, like souping up the web site and writing intros for managers, I'm not sure I have much advice except I don't think it's such a good idea. :-)
Yes. This is definitely not a good idea. First of all, do we really want to attract managers who are swayed by glossy brochure marketing material? We have a top-notch user community at the moment, and I know there are a lot of really interesting projects going on in the Twistedverse; while it is certainly tempting to attempt Total World Domination (TM), eliminating PHP/mod_perl/your favorite sucky web technology, the only real benefit is enabling smart people who work for stupid people to have a good time. We could always use improvement of our technical documentation, but I think that as a technical community, we generally have a poor understanding of what makes the stereotypical bad manager's mind work. We need to be able to understand their legitimate concerns without caving in to their apparently irrational need for a security blanket of "web services" and "b2b p2p" and "enterprise ready". I have a feeling that if we _did_ try to produce such a website, the resulting material would sound indistinguishable (to our ears) from the average industry rag advertisement, but that it would feel vaguely insulting to the people we were trying to reach, because it would be an unintentional parody of that style.
On Thu, Jun 05, 2003 at 12:36:41PM +1000, Andrew Bennetts wrote:
On Wed, Jun 04, 2003 at 10:15:01PM -0400, Peter Hansen wrote:
jml@ids.org.au wrote:
3. Coil.
I have only one thing to say in this area, which is please don't anyone think about developing this just because you think you need to in order to help convince someone to use Twisted.
I've seen the old coil, and heard discussion on what the new coil will do, and I'm sufficiently excited to believe it's *very* worthwhile...
Yes. Coil (if it lives up to it's promises) is something that I would almost certainly use a great deal. I find TAPs and command-line twistd launchings to be somewhat ... confusing. At least, inasmuch as I feel the need to remember where everything is at, and what I've done, etc. Coil promises to be an admin server that can be used to bring up your services, configure them, add them, restart them, shut them down and all of that. Just being able to *see* everything at once So, yes, I agree with everything spiv said. jml
participants (10)
-
Andrew Bennetts -
Andrew Dalke -
Donovan Preston -
Glyph Lefkowitz -
jml＠ids.org.au -
jml＠mumak.net -
Peter Hansen -
Philippe Lafoucrière -
screwtape＠froup.com -
Syver Enstad