[Twisted-Python] Task-based documentation started

[exarkun at twistedmatrix.com]

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".

Jean-Paul