I seem to be missing the link on the page: http://twistedmatrix.com/trac/wiki/Documentation Sent via iPhone Is your e-mail Premiere? On Apr 20, 2010, at 18:38, exarkun@twistedmatrix.com wrote:

On 20 Apr, 11:25 pm, jasonjwwilliams@gmail.com wrote:

...

Hi Guys,

Just been going through the twisted.web series JP put together (http://jcalderone.livejournal.com/tag/sixty%20seconds)...these are terrific. Turn the bottom one into serving a "Hello World" Resource and you've got a much simpler Hello World than the Tornado site (not to start a war on Tornado...their URL dispatch approach is pretty nice).

Is there is a reason these aren't linked to on the frontpage of twistedmatrix.com...preferably with the short hello world above it? They're much more accessible than the Twisted Web tutorials under docs.

They're linked from the Twisted Web documentation page. They're probably not linked from the front page because no one has taken the time to redo the website design in a way that allows direct links to this kind of specific documentation.

Jean-Paul

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

That was kind of my point... ;) It's pretty buried. It's not under docs directly and it's not under the "read this first!" about web stuff. And yes I'm volunteering to reorg. -J On Tue, Apr 20, 2010 at 7:30 PM, Jessica McKellar <jessica.mckellar@gmail.com> wrote:

Hi Jason,

It's under the web howto link on that page:

http://twistedmatrix.com/trac/wiki/Documentation ===> http://twistedmatrix.com/documents/current/web/howto/ ===> http://twistedmatrix.com/documents/current/web/howto/web-in-60/index.html

-Jessica

On Tue, Apr 20, 2010 at 9:23 PM, Jason J. W. Williams <jasonjwwilliams@gmail.com> wrote:

...

I seem to be missing the link on the page: http://twistedmatrix.com/trac/wiki/Documentation

Sent via iPhone

Is your e-mail Premiere?

On Apr 20, 2010, at 18:38, exarkun@twistedmatrix.com wrote:

...

On 20 Apr, 11:25 pm, jasonjwwilliams@gmail.com wrote:

...

Hi Guys,

Just been going through the twisted.web series JP put together (http://jcalderone.livejournal.com/tag/sixty%20seconds)...these are terrific. Turn the bottom one into serving a "Hello World" Resource and you've got a much simpler Hello World than the Tornado site (not to start a war on Tornado...their URL dispatch approach is pretty nice).

Is there is a reason these aren't linked to on the frontpage of twistedmatrix.com...preferably with the short hello world above it? They're much more accessible than the Twisted Web tutorials under docs.

They're linked from the Twisted Web documentation page.  They're probably not linked from the front page because no one has taken the time to redo the website design in a way that allows direct links to this kind of specific documentation.

Jean-Paul

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

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

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

I guess I am. :) Honestly, we've used Twisted in my org for quite some time and until I was forced to use it my view of it was colored by my infrequent beatings by it and the derisive comments of the primary maintainer at that time. With the 4 hours I spent actually learning the concepts, Twisted is no longer a black box...it makes sense. That and I've optimized/re-factored a bunch of code to work with that theory instead of against it. Huge benefits. I'd say the biggest barrier to entry is the documentation. And let's face it...there's no reason Twisted shouldn't be used by more folks. It's great...but learning it feels like a frat hazing. That's largely because reading the docs feels like learning from that comp sci prof who was smart...but wasn't smart enough to explain the concepts at your level. Let's take Tornado for a second...right now I'm building a web API for our services and I'm in platform selection mode. My experience with Twisted.web's URL dispatching system made me want to cry. Tornado was a breeze to use. But here's the problem: 1.) There's no good async libraries for Tornado...so if I want to integrate with Redis or MySQL or anything, I've got to accept that I'm going to block when it's not necessary and live with that. 2.) Tornado's performance from the the benchmarks I've read is only between 15% and 30% better than twisted.web. 2 is not enough to justify 1, because let's face it (and yeah I'm coming to a point) 1 is going to kill your butt often enough to make 2 not matter. But because I'm pretty comfortable with Twisted now...it makes more sense for me to write my own dispatcher that emulates Tornado's than give up all the rock-hard awesome features and reliability of Twisted. deferToThread may not be the preferred way of handling a blocking task...but when you need it, you need it. ...so my point is...Twisted's PR problem is it needs more accessible docs. They need to be understandable, entertaining...and pretty. It all starts with that front page...and the web app in 10 lines right smack dab there. I'm going to start with the front page...and then I'm going to write some articles on my blog that are what I wanted when I was learning Twisted. Hopefully, they'll be of use to someone. -J On Wed, Apr 21, 2010 at 6:15 PM, Glyph Lefkowitz <glyph@twistedmatrix.com> wrote:

On Apr 20, 2010, at 7:06 PM, Jason J. W. Williams wrote:

And yes I'm volunteering to reorg.

Wow, you really are a glutton for punishment, aren't you? :) Go ahead and create an alternate front-page wiki page, and let the list know when it's ready so we can pile on and critique. I'm sure it wouldn't be too hard to do better than what's there, though. Looking forward to it, -glyph _______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Naw...I meant what I wrote. ;) exarkun's is great...it's web focused. I'll post to them to the list and y'all can see if its worthwhile. -J On Wed, Apr 21, 2010 at 7:05 PM, ssteinerX@gmail.com <ssteinerx@gmail.com> wrote:

On Apr 21, 2010, at 8:53 PM, Jason J. W. Williams wrote:

...

But because I'm pretty comfortable with Twisted now...it makes more sense for me to write my own dispatcher that emulates Tornado's than give up all the rock-hard awesome

My spam filter almost killed you on that phrase.  I think you mean rock-solid.

...

...so my point is...Twisted's PR problem is it needs more accessible docs. They need to be understandable, entertaining...and pretty. It all starts with that front page...and the web app in 10 lines right smack dab there.

I'm going to start with the front page...and then I'm going to write some articles on my blog that are what I wanted when I was learning Twisted. Hopefully, they'll be of use to someone.

Cool.  See exarkun's Twisted in 60 Seconds series; maybe fill in the things that are still not clear after that?

S

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

That looks pretty darn interesting. -J On Wed, Apr 21, 2010 at 7:30 PM, Kevin Horn <kevin.horn@gmail.com> wrote:

This blog series is also totally rock-a-licious.

http://krondo.com/blog/?page_id=1327

Kevin Horn

On Wed, Apr 21, 2010 at 8:22 PM, Jason J. W. Williams <jasonjwwilliams@gmail.com> wrote:

...

Naw...I meant what I wrote. ;) exarkun's is great...it's web focused. I'll post to them to the list and y'all can see if its worthwhile.

-J

On Wed, Apr 21, 2010 at 7:05 PM, ssteinerX@gmail.com <ssteinerx@gmail.com> wrote:

...

On Apr 21, 2010, at 8:53 PM, Jason J. W. Williams wrote:

...

But because I'm pretty comfortable with Twisted now...it makes more sense for me to write my own dispatcher that emulates Tornado's than give up all the rock-hard awesome

My spam filter almost killed you on that phrase.  I think you mean rock-solid.

...

...so my point is...Twisted's PR problem is it needs more accessible docs. They need to be understandable, entertaining...and pretty. It all starts with that front page...and the web app in 10 lines right smack dab there.

I'm going to start with the front page...and then I'm going to write some articles on my blog that are what I wanted when I was learning Twisted. Hopefully, they'll be of use to someone.

Cool.  See exarkun's Twisted in 60 Seconds series; maybe fill in the things that are still not clear after that?

S

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

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

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

On Wed, Apr 21, 2010 at 7:53 PM, Jason J. W. Williams < jasonjwwilliams@gmail.com> wrote:

I'd say the biggest barrier to entry is the documentation. And let's face it...there's no reason Twisted shouldn't be used by more folks. It's great...but learning it feels like a frat hazing. That's largely because reading the docs feels like learning from that comp sci prof who was smart...but wasn't smart enough to explain the concepts at your level.

The docs really are about to get a whole lot better. No really, any minute now. The Sphinx conversion is not dead! I've just been busy... And once that's done I think it'll be a whole lot easier to write and maintain things, not to mention read the docs. Kevin Horn

On Wed, Apr 21, 2010 at 9:48 PM, <exarkun@twistedmatrix.com> wrote:

So about the conversion, I wonder if we can start to generate the Sphinx version of the docs on buildbot sometime soon, and perhaps host them alongside the current docs, as the first step in phasing out the current version?

I suppose we could do this, if you think it would help. Note that the lore2sphinx script requires Python 2.6 and I think at least Sphinx 0.6.4 (I'm using 0.6.5).

How automated is the conversion process now? Are errors reported such that people could start looking at them and fixing the issues? It seems like you've done almost all of the hard work, and the rest is dealing with some edge cases in lore or restructured text, and that might be more easily spread out amongst more people.

Jean-Paul

I think the automatic conversion process has reached the point of diminishing returns. I've got it down to about 13 warnings in the Sphinx build process, though there are still some markup errors in the output. Trying to make the conversion handle these seems to just introduce more errors in other places. In other words I think it's time to create a branch with the Sphinxified docs and do a manual review. I've got a basic transition plan sketched out here: http://twistedsphinx.funsize.net/transition_plan.html That's just basically an outline of a plan Glyph and I hashed out during the Twisted sprint at PyCon. Ideas and criticisms welcome. Kevin Horn

On Thu, Apr 22, 2010 at 11:51 AM, <exarkun@twistedmatrix.com> wrote:

On 02:57 pm, kevin.horn@gmail.com wrote:

...

On Wed, Apr 21, 2010 at 9:48 PM, <exarkun@twistedmatrix.com> wrote:

...

So about the conversion, I wonder if we can start to generate the Sphinx version of the docs on buildbot sometime soon, and perhaps host them alongside the current docs, as the first step in phasing out the current version?

I suppose we could do this, if you think it would help. Note that the lore2sphinx script requires Python 2.6 and I think at least Sphinx 0.6.4 (I'm using 0.6.5).

Shouldn't be a problem.

...

...

How automated is the conversion process now? Are errors reported such that people could start looking at them and fixing the issues? It seems like you've done almost all of the hard work, and the rest is dealing with some edge cases in lore or restructured text, and that might be more easily spread out amongst more people.

Jean-Paul

I think the automatic conversion process has reached the point of diminishing returns. I've got it down to about 13 warnings in the Sphinx build process, though there are still some markup errors in the output. Trying to make the conversion handle these seems to just introduce more errors in other places.

Would it be easier to fix these by changing the lore sources?

Jean-Paul

I seriously doubt it. In fact I think it would be much more difficult. Other than the 13 build warnings I mentioned above, almost all of the rest of the markup errors are things like a missing space character. Fixing this in the lore sources would require: 1) removing most if not all indentation from all the lore sources 2) making sure every <b>, <i>, <code>, <a> tag (and some others I'm sure) have exactly the same spacing before and after them...including tabs, newlines, etc. 3) revamping lore2sphinx to stop doing all the workarounds it currently does I think it will be much easier to go through the ReST sources (which IMO will need to be done anyway) and add spaces or whatever where needed. Kevin Horn Kevin Horn

On 12:53 am, jasonjwwilliams@gmail.com wrote:

I guess I am. :)

I'm going to start with the front page...and then I'm going to write some articles on my blog that are what I wanted when I was learning Twisted. Hopefully, they'll be of use to someone.

If it's of any use, someone started trying to do this, and got at least as far as deleting all of the front page content: http://twistedmatrix.com/trac/wiki/TestFrontPage Jean-Paul