On Mon, Jan 31, 2011 at 5:22 PM, Glyph Lefkowitz <glyph@twistedmatrix.com>wrote:
On Jan 31, 2011, at 11:41 AM, Tom Davis wrote:
Thoughts?
I'll have to write more later, but maybe you should read *all* of the existing twisted.web documentation first? I am sorry to say it, but this seems like a less informative and more confusing version of < http://twistedmatrix.com/documents/10.2.0/web/howto/web-in-60/static-content...> and < http://twistedmatrix.com/documents/10.2.0/web/howto/web-in-60/wsgi.html>.
It is certainly less informative than those. I borrowed what I did from the larger "using twisted.web" document just to illustrate some intent. It is by no means finished or necessarily representative of the actual content of those sections (static files and wsgi).
For example: Why are you talking about SimpleHTTPServer? Does *anybody* actually use that or know about it any more? I haven't heard it brought up in years. For people who do know about what it is, comparing it to that makes it sound like twisted.web is a toy and should not be used in production, since SimpleHTTPServer certainly isn't capable of serving a real site.
Fair enough.
Again, the problem is not really the content, we have a surprising amount of content, it's fixing the architecture so that people *find* the content that they're looking for.
Right, I agree. I'm not saying content *is* the problem. The problem is both discoverability from the standpoint of ToC, orphaned pages, etc. *and* from the per-document standpoint. What one really wants to *do* is often mixed in with the details of how you could do *everything* related to that one task. Or it's duplicated. Or in a random file elsewhere. Perhaps it's best to say that you could consider the text in that tutorial to be the equivalent of "Lorem Ipsum", except context-relevant enough to get across the general idea of splitting things up by task, complexity, and level of existing knowledge (or desired future knowledge). Take < http://twistedmatrix.com/documents/10.2.0/web/howto/web-in-60/static-content...
:
Tell me the one command I need to serve a directory, *then* show me the code that one command effectively runs and vaguely what it does. Then tell me where I can learn about twistd and reactors and Sites and Files. And take that chunk of [usage -> implementation -> further understanding] and call it a Task (or sub-Task in the case of serving static files). The content is already there; it's just about arranging it properly. I hope that helps clear up my opinion a bit.
_______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python