[Twisted-Python] Proposed new homepage
Our current page is not good at pulling in potential new users: * There's no quick examples of how nice Twisted is. * It takes 3 clicks (3!) to find basic documentation, with lots of scope for getting lost along the way. I propose to fix this by adding code examples, and relevant direct documentation links. A very preliminary pass, still lacking things like syntax highlighting, can be found here: http://twistedmatrix.com/trac/wiki/ProposedWikiStart What do you think?
On 10/09/2011 02:44 PM, Itamar Turner-Trauring wrote:
Opinions from a long-time observer, who is not offering to contribute -- sorry! totally swamped ... :( * I agree that quick examples should be more accessible. I think the ones that go (possibly) somewhere on the homepage need to be carefully chosen (whatever that means ;). I confess that my preference would be to have the "What is Twisted?" section extremely short (like maybe a 2-sentence paragraph with its current links) and then the "Quick Links" section right after that but have the "More Useful Pointers" section perhaps as an expandable part of the Quick Links, so that the next section could be Quick Examples and at least the beginning of the examples would be visible without scrolling (I like to avoid having to scroll to see the major structures on a page). * I don't get your point about 3 clicks to find basic documentation -- doesn't the link to "Twisted Core Documentation" in the 3rd paragraph get you there in one click? Of course, the "basic documentation" will be nicer when the Sphinx-based docs arrive, I think ... Steve
Hi! On Sun, Oct 09, 2011 at 02:44:41PM -0400, Itamar Turner-Trauring wrote:
http://twistedmatrix.com/trac/wiki/ProposedWikiStart
What do you think?
I like the approach to instantly "dive into" the library by showing some code. But I have a programming background - not sure if all (relevant) visitors will be happy with this.
Twisted is an event-driven networking engine written in Python and licensed under the MIT license.
Is the license really so important that it should be mentioned in the first paragraph? If it is, you might want to consider splitting the sentence. And yes, I know that the current homepage starts with the same sentence ;-). The following summary of Twisted projects on the current homepage might be a good completion of the first paragraph:
One comment on the first code example:
It might be better to just define the `protocol` class variable and leave the instantiation to the default implementation of `buildProtocol`. Otherwise, the reader might assume that overriding `buildProtocol` is always necessary. Even worse, she might think that just returning an instance is enough; AFAIK, `buildProtocol` should also set the instance's `factory`. Of course that is an implementation detail, but I don't think we should set visitors on the wrong track right at the beginning ;-). Best regards, -- Albert Brandl Weiermayer Solutions GmbH | Abteistraße 12, A-4813 Altmünster phone: +43 (0) 720 70 30 14 | fax: +43 (0) 7612 20 3 56 web: http://www.weiermayer.com
On Mon, 2011-10-10 at 09:20 +0200, Albert Brandl wrote:
Open source and not GPL is probably the important bit.
I get the impression some people think Twisted is complex and big because of all the features it has. So first I want to show them with code "look it's so simple"... and only then give the full list of features.
I have just closed two tickets making buildProtocol explicitly used in both the server and client howtos, and I've also updated a relevant code example in the website's FAQ. The current way of doing things, setting an attribute on Factory, is really bad from an educational point of view, since it makes protocol creation "magic". By having an explicit buildProtocol users know where protocol instances come from, and how to override this creation.
buildProtocol does not always need to set factory as an attribute, you can just return a protocol instance. If you do need the factory, better to pass it in to Protocol's __init__ explicitly instead of having an extra attribute shoved on later.
On Oct 10, 2011, at 8:30 AM, Itamar Turner-Trauring wrote:
On Mon, 2011-10-10 at 09:20 +0200, Albert Brandl wrote:
I emphatically agree. It might be good to eventually have more of a link – demonstrate how the echo server actually leads into the web server – but the parallel structure of the examples there at least hints at it. Maybe we could have one more: like a 'hello world' IRC bot or something?
These tickets are <http://twistedmatrix.com/trac/ticket/5044> and <http://twistedmatrix.com/trac/ticket/4761> if anyone wants more details on this. The existing behavior is convenient, and isn't going away, but it's very difficult for new users to infer what's going on without reading all of protocol.Factory's implementation.
Nice effort. I also believe that getting down to the details (the code) will get a lot more people interested. One question: "Scalable web applications"? What makes them scalable? Either drop the word, or explain. -- Johan Rydberg Product Designer Edgeware AB Mäster Samuelsgatan 56 SE-111 21 Stockholm, Sweden
On Mon, 2011-10-10 at 11:22 +0200, Johan Rydberg wrote:
Hm. I need a short way of explaining "can support large numbers of long-running queries without falling over like a thread/process-pool based web server would". I guess that's not that hard to write ;) I wonder if the example could easily demonstrate that... perhaps a streaming countdown display?
On Oct 9, 2011, at 2:44 PM, Itamar Turner-Trauring wrote:
This is a fantastic effort. I don't think it's perfect, but I do think it's substantially better than what we have now (modulo "scalable" which I already addressed in another message). We should continue to talk about it and work on it, but I think we should switch over to this new and improved thing ASAP. Unless someone has a serious objection, I think we should replace the front page later today. (Itamar, do you want to do the honors, or shall I?) The main thing I'd like to see added next would be some verbiage around twistd plugins, like "running a web server is as easy as 'twistd web --path .'". I'd really like to stress that you don't need to be a programmer to use Twisted; we aren't ever going to get a good system administration story unless more ops people hear about it and start playing with it :). One other minor tweak: 'Quick Links' was always a dumb heading. "More Information", maybe? -glyph
On Mon, 2011-10-10 at 09:47 -0400, Glyph wrote:
Unless someone has a serious objection, I think we should replace the front page later today. (Itamar, do you want to do the honors, or shall I?)
I'll try to do it this evening, after adding syntax highlighting (half manually, ugh) and fixing the comments mentioned here (scalability, Quick Links).
Oh - I am going to need admin permission on the wiki, I can't actually edit the front page right now :)
On 10/09/2011 02:44 PM, Itamar Turner-Trauring wrote:
Opinions from a long-time observer, who is not offering to contribute -- sorry! totally swamped ... :( * I agree that quick examples should be more accessible. I think the ones that go (possibly) somewhere on the homepage need to be carefully chosen (whatever that means ;). I confess that my preference would be to have the "What is Twisted?" section extremely short (like maybe a 2-sentence paragraph with its current links) and then the "Quick Links" section right after that but have the "More Useful Pointers" section perhaps as an expandable part of the Quick Links, so that the next section could be Quick Examples and at least the beginning of the examples would be visible without scrolling (I like to avoid having to scroll to see the major structures on a page). * I don't get your point about 3 clicks to find basic documentation -- doesn't the link to "Twisted Core Documentation" in the 3rd paragraph get you there in one click? Of course, the "basic documentation" will be nicer when the Sphinx-based docs arrive, I think ... Steve
Hi! On Sun, Oct 09, 2011 at 02:44:41PM -0400, Itamar Turner-Trauring wrote:
http://twistedmatrix.com/trac/wiki/ProposedWikiStart
What do you think?
I like the approach to instantly "dive into" the library by showing some code. But I have a programming background - not sure if all (relevant) visitors will be happy with this.
Twisted is an event-driven networking engine written in Python and licensed under the MIT license.
Is the license really so important that it should be mentioned in the first paragraph? If it is, you might want to consider splitting the sentence. And yes, I know that the current homepage starts with the same sentence ;-). The following summary of Twisted projects on the current homepage might be a good completion of the first paragraph:
One comment on the first code example:
It might be better to just define the `protocol` class variable and leave the instantiation to the default implementation of `buildProtocol`. Otherwise, the reader might assume that overriding `buildProtocol` is always necessary. Even worse, she might think that just returning an instance is enough; AFAIK, `buildProtocol` should also set the instance's `factory`. Of course that is an implementation detail, but I don't think we should set visitors on the wrong track right at the beginning ;-). Best regards, -- Albert Brandl Weiermayer Solutions GmbH | Abteistraße 12, A-4813 Altmünster phone: +43 (0) 720 70 30 14 | fax: +43 (0) 7612 20 3 56 web: http://www.weiermayer.com
On Mon, 2011-10-10 at 09:20 +0200, Albert Brandl wrote:
Open source and not GPL is probably the important bit.
I get the impression some people think Twisted is complex and big because of all the features it has. So first I want to show them with code "look it's so simple"... and only then give the full list of features.
I have just closed two tickets making buildProtocol explicitly used in both the server and client howtos, and I've also updated a relevant code example in the website's FAQ. The current way of doing things, setting an attribute on Factory, is really bad from an educational point of view, since it makes protocol creation "magic". By having an explicit buildProtocol users know where protocol instances come from, and how to override this creation.
buildProtocol does not always need to set factory as an attribute, you can just return a protocol instance. If you do need the factory, better to pass it in to Protocol's __init__ explicitly instead of having an extra attribute shoved on later.
On Oct 10, 2011, at 8:30 AM, Itamar Turner-Trauring wrote:
On Mon, 2011-10-10 at 09:20 +0200, Albert Brandl wrote:
I emphatically agree. It might be good to eventually have more of a link – demonstrate how the echo server actually leads into the web server – but the parallel structure of the examples there at least hints at it. Maybe we could have one more: like a 'hello world' IRC bot or something?
These tickets are <http://twistedmatrix.com/trac/ticket/5044> and <http://twistedmatrix.com/trac/ticket/4761> if anyone wants more details on this. The existing behavior is convenient, and isn't going away, but it's very difficult for new users to infer what's going on without reading all of protocol.Factory's implementation.
Nice effort. I also believe that getting down to the details (the code) will get a lot more people interested. One question: "Scalable web applications"? What makes them scalable? Either drop the word, or explain. -- Johan Rydberg Product Designer Edgeware AB Mäster Samuelsgatan 56 SE-111 21 Stockholm, Sweden
On Mon, 2011-10-10 at 11:22 +0200, Johan Rydberg wrote:
Hm. I need a short way of explaining "can support large numbers of long-running queries without falling over like a thread/process-pool based web server would". I guess that's not that hard to write ;) I wonder if the example could easily demonstrate that... perhaps a streaming countdown display?
On Oct 9, 2011, at 2:44 PM, Itamar Turner-Trauring wrote:
This is a fantastic effort. I don't think it's perfect, but I do think it's substantially better than what we have now (modulo "scalable" which I already addressed in another message). We should continue to talk about it and work on it, but I think we should switch over to this new and improved thing ASAP. Unless someone has a serious objection, I think we should replace the front page later today. (Itamar, do you want to do the honors, or shall I?) The main thing I'd like to see added next would be some verbiage around twistd plugins, like "running a web server is as easy as 'twistd web --path .'". I'd really like to stress that you don't need to be a programmer to use Twisted; we aren't ever going to get a good system administration story unless more ops people hear about it and start playing with it :). One other minor tweak: 'Quick Links' was always a dumb heading. "More Information", maybe? -glyph
On Mon, 2011-10-10 at 09:47 -0400, Glyph wrote:
Unless someone has a serious objection, I think we should replace the front page later today. (Itamar, do you want to do the honors, or shall I?)
I'll try to do it this evening, after adding syntax highlighting (half manually, ugh) and fixing the comments mentioned here (scalability, Quick Links).
Oh - I am going to need admin permission on the wiki, I can't actually edit the front page right now :)
participants (6)
-
Albert Brandl -
Glyph -
Itamar Turner-Trauring -
Johan Rydberg -
Jonathan Lange -
Stephen Waterbury