[Twisted-Python] Task-based documentation started

[Tom Davis]

On Mon, Jan 31, 2011 at 6:19 PM, <exarkun at twistedmatrix.com> wrote:

> On 10:39 pm, tom at 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 at twistedmatrix.com
> http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20110201/79dc8ef8/attachment.html>