<div class="gmail_quote">On Mon, Jan 31, 2011 at 6:19 PM, <span dir="ltr"><<a href="mailto:exarkun@twistedmatrix.com">exarkun@twistedmatrix.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<div class="im">On 10:39 pm, <a href="mailto:tom@recursivedream.com">tom@recursivedream.com</a> wrote:<br>
><br>
>Take <<br>
><a href="http://twistedmatrix.com/documents/10.2.0/web/howto/web-in-60/static-" target="_blank">http://twistedmatrix.com/documents/10.2.0/web/howto/web-in-60/static-</a><br>
>content.html<br>
>>:<br>
><br>
>Tell me the one command I need to serve a directory, *then* show me the<br>
>code<br>
>that one command effectively runs and vaguely what it does.<br>
<br>
</div>I think this is partially a disagreement over what tasks we actually<br>
want to document. If the command line interface gets primacy in the<br>
documentation, then I think you're writing documentation for end users<br>
(sys admins, non-programmers). I don't know about anyone else, but this<br>
category of documentation hadn't really crossed my mind before.<br>
<br>
I think that (ultimately) this is good documentation to have, but I<br>
don't know if it's as important as getting the programmer-oriented<br>
documentation in better shape.<br>
<br>
Another point to consider is that "twistd web" (and most other twistd<br>
plugins we provide) are semi-random mish mashes of functionality. They<br>
have accreted by contribution from many different people over the years<br>
with no governing design or goal aside from "expose features from the<br>
command line". This does not make them the friendliest tools around.<br>
The functionality they are missing is often surprising, particularly<br>
when contrasted with some of the (non-)functionality they do provide.<br>
<br>
I don't want to say that they do not bear documenting until their state<br>
is improved, but if we focused on other areas first, maybe we would have<br>
something better to document when we eventually get around to things<br>
like "twistd web".<br></blockquote><div><br></div><div>I look at it from a pragmatic point of view: If the task is called "serving HTML" and you <i>can</i> 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 <i>right now</i>. 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).</div>
<div><br></div><div>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.</div>
<div><br></div><div>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.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<br>
Jean-Paul<br>
<div><div></div><div class="h5"><br>
_______________________________________________<br>
Twisted-Python mailing list<br>
<a href="mailto:Twisted-Python@twistedmatrix.com">Twisted-Python@twistedmatrix.com</a><br>
<a href="http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python" target="_blank">http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python</a><br>
</div></div></blockquote></div><br>