Earlier quoted context omitted.
I'd rather struggle with difficulty of concept than difficulty in finding information.
What self-respecting programmer doesn't idle in the freenode channels of the software packages he or she is learning? You immerse yourself in the community and ask intelligent questions; if anything, just to see what the community is like before you commit your project to depend on something written by either douchebags or morons. I did just that with the twisted community and I found them a good bunch.
Open Source Is Really About Documentation – Twisted vs. Tornado
21–30 of 30 posts
Re: Open Source Is Really About Documentation – Twisted vs. Tornado
#22I have built several twisted apps which are in use in production environments, including web and jabber/xmpp apps. I love twisted, and use it whenever possible... ...and I agree completely with the op. Twisted is powerful, flexible, well architected, and reliable. It is also damn near impossible to get over the steep learning curve and to actually USE it. Show me a competent Twisted developer, and I'll show you someo…
http://twistedmatrix.com/projects/core/documentation/howto/t... What's wrong with that? Seems quite comprehensible to me...
Attention to small details is the greater part of friendliness.
Re: Open Source Is Really About Documentation – Twisted vs. Tornado
#23I have built several twisted apps which are in use in production environments, including web and jabber/xmpp apps. I love twisted, and use it whenever possible... ...and I agree completely with the op. Twisted is powerful, flexible, well architected, and reliable. It is also damn near impossible to get over the steep learning curve and to actually USE it. Show me a competent Twisted developer, and I'll show you someo…
Definitely agree on the learning curve. I'm using twisted for a distributed computing framework that is custom tailored for our requirements (looked into Hadoop, disco, etc. but decided against for valid technical and/or logistical reasons). I go to a lot of pains so that clients of my framework never have to touch or even see twisted though it is under the hood. I think I spent about a week in the beginning really w…
Tornado does look nicer and I have to admit purely from the documentation. I read through it for about 10 minutes just now and I can for the first time actually see how it would work within the realms of our project.
With that said it might be a useful way to figure out what Twisted is all about too....
Re: Open Source Is Really About Documentation – Twisted vs. Tornado
#24I have built several twisted apps which are in use in production environments, including web and jabber/xmpp apps. I love twisted, and use it whenever possible... ...and I agree completely with the op. Twisted is powerful, flexible, well architected, and reliable. It is also damn near impossible to get over the steep learning curve and to actually USE it. Show me a competent Twisted developer, and I'll show you someo…
http://twistedmatrix.com/projects/core/documentation/howto/t... What's wrong with that? Seems quite comprehensible to me...
The best investment in terms of mindshare the twisted project could make at this point would be to simply sit down and write documentation.
Grab sphinx (or another tool that makes doc-writing fun) and start out by writing a page about each Class that is being used in these examples. Why does it exist, what role does it have and don't forget the link to the API doc. Then I'd suggest to make a high-level overview, perhaps even with a little diagram, that explains how everything plays together in the various application types. Hyperlinks to the previously mentioned detail-pages should then work wonders for anyone exploring the project.
Writing good documentation is hard, but you only have to do it once. The lack of documentation on the other hand forces every new user to wrap their heads around innocent lines like this:
internet.TCPServer(79, factory).setServiceParent(
service.IServiceCollection(application))
I'm surely not the only one who put off learning about that whole Service metaphor and stuck with the simpler examples until I absolutely couldn't avoid it any longer. That's not the way you want users to approach your framework.Re: Open Source Is Really About Documentation – Twisted vs. Tornado
#25Earlier quoted context omitted.
http://twistedmatrix.com/projects/core/documentation/howto/t... What's wrong with that? Seems quite comprehensible to me...
It's indeed the starting point to learn the fundamentals - but becomes almost hilarious after step 4 when they begin to introduce Components, Adapters, Perspective Broker and other things without losing many words about what all that stuff does, much less how to re-arrange it for custom needs. The best investment in terms of mindshare the twisted project could make at this point would be to simply sit down and write…
Making documentations (and contributions to it) a first-class contribution with its bugs & discussions & refactorings, and fun to write (the way the Django project handles it) would probably also go quite a way towards that.
Re: Open Source Is Really About Documentation – Twisted vs. Tornado
#26Earlier quoted context omitted.
It's indeed the starting point to learn the fundamentals - but becomes almost hilarious after step 4 when they begin to introduce Components, Adapters, Perspective Broker and other things without losing many words about what all that stuff does, much less how to re-arrange it for custom needs. The best investment in terms of mindshare the twisted project could make at this point would be to simply sit down and write…
> The best investment in terms of mindshare the twisted project could make at this point would be to simply sit down and write documentation. Making documentations (and contributions to it) a first-class contribution with its bugs & discussions & refactorings, and fun to write (the way the Django project handles it) would probably also go quite a way towards that.
Currently the barrier of entry is too high and I guess too few people are deep enough in twisted to explain all the why's of even a simple baseline example properly.
It's kind of a deadlock situation because without that lowlevel insight it's also hard to get confident enough to contribute high-level docs.
Re: Open Source Is Really About Documentation – Twisted vs. Tornado
#27Earlier quoted context omitted.
> The best investment in terms of mindshare the twisted project could make at this point would be to simply sit down and write documentation. Making documentations (and contributions to it) a first-class contribution with its bugs & discussions & refactorings, and fun to write (the way the Django project handles it) would probably also go quite a way towards that.
Yup, agreed. Creating and endorsing good documentation is an artform in itself. Currently the barrier of entry is too high and I guess too few people are deep enough in twisted to explain all the why's of even a simple baseline example properly . It's kind of a deadlock situation because without that lowlevel insight it's also hard to get confident enough to contribute high-level docs.
Thing is, through checking out Django I realized you don't really need to be "deep enough" to contribute to that stuff. The thousand-cut effects applies, and when you're trying to make heads or tails of the doc, you're bleeding from these thousand cuts so you know and understand the doc's pain points. If doc contribs are first-class, then right as you understand the issues and what the doc tries to say, you'll be steered towards opening a documentation bug (and maybe even contributing a patch) for that part.
Maybe it's just doing to be a bit of wording, maybe it'll be a link or two to other relevant parts of the doc; maybe it'll be things you'll have figured through your sweat and tears, maybe something you'll have learned by asking a question on IRC.
But even as a beginner, you'll have added a little stone and made the doc slightly better through your current understanding. And it's enough.
I barely contributed to Django myself, but my first ever contrib was simply pointing out that the `now` tag's format character `n` produced an RFC 2822 date, not an RFC 822 one as written in the doc at the time. It was almost nothing, but it still very slightly improved the documentation for the next guy reading it, and it actually made me feel involved in the project. Even though I didn't have anywhere near the knowledge of the codebase to contribute to the code itself.
edit: and re the thousand cuts effect, that's the great thing about making beginners contribute: "old timers" don't notice or remember these small issues (which pile up), because they fill in he blanks or missing parts through their knowledge.
Re: Open Source Is Really About Documentation – Twisted vs. Tornado
#28Just remember MySQL - its success was about documentation (the most), community (as a result) and some PR. It is so strange to create reusable components without detailed guides. The nginx had this very problem. If it could get a user-friendly documentation it will earn more adoptions.
Re: Open Source Is Really About Documentation – Twisted vs. Tornado
#29Re: Open Source Is Really About Documentation – Twisted vs. Tornado
#30As usual, a simple "this versus that" comparison is only useful as an intellectual exercise. Tornado is a web framework, in many ways closer to Django than Twisted. Beyond that the underlying approaches are different - Tornado does not use deferreds. There are a number of great projects that use Twisted. Soon many new projects will use Tornado. But the frameworks' respective documentation does not tell the story.
> Tornado is a web framework Not really. It's the combination of an asynchronous HTTP server and an optional web framework. And work is being done [to add WSGI support]( http://github.com/facebook/tornado/commit/8ca616088cfb26ff19... ) so other frameworks can be plugged into the server. At its core, Tornado is a server not a framework.
Twisted is, at least for now, more general purpose. Can't wait to see where Tornado goes though.