On Mon, Jan 31, 2011 at 6:19 PM, <exarkun@twistedmatrix.com> wrote:
On 10:39 pm, tom@recursivedream.com wrote:
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.
I think this is partially a disagreement over what tasks we actually want to document. If the command line interface gets primacy in the documentation, then I think you're writing documentation for end users (sys admins, non-programmers). I don't know about anyone else, but this category of documentation hadn't really crossed my mind before.
I think that (ultimately) this is good documentation to have, but I don't know if it's as important as getting the programmer-oriented documentation in better shape.
Another point to consider is that "twistd web" (and most other twistd plugins we provide) are semi-random mish mashes of functionality. They have accreted by contribution from many different people over the years with no governing design or goal aside from "expose features from the command line". This does not make them the friendliest tools around. The functionality they are missing is often surprising, particularly when contrasted with some of the (non-)functionality they do provide.
I don't want to say that they do not bear documenting until their state is improved, but if we focused on other areas first, maybe we would have something better to document when we eventually get around to things like "twistd web".
I look at it from a pragmatic point of view: If the task is called "serving HTML" and you *can* do that with a single command line argument, I'm willing to possibly waste a sentence exposing something unideal or incomplete if it fixes the visitor's problem *right now*. That's simply not a lot of effort for a good deal of gain. Immediately after that command line section should be a dive into the actual code (or at least enough to get serving via a python file). I suppose you may disagree with task-based views entirely. The using twisted.web "howto" isn't really one at all. It covers many / all of the serving aspects of twisted.web which is cool and necessary, but the actual building block tasks are buried. It's still early and I'm not sure how much sense I'm making here. I think a more complete example of what I'm talking about could serve to remedy a lot of these issues and show that what everybody wants (and already has) is still present, just moved to a more logical place.
Jean-Paul
_______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python