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