[Twisted-Python] Task-based documentation started

[Tom Davis]

On Mon, Jan 31, 2011 at 5:22 PM, Glyph Lefkowitz <glyph at 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.html>
> 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.html
>:

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 at twistedmatrix.com
> http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20110131/c5f03fa6/attachment.html>