[Twisted-Python] Task-based documentation started

[Glyph Lefkowitz]

On Jan 31, 2011, at 3: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.

Yes, and that's not good.  We should be thinking about those people a little more :).  Twisted is still mostly a library, but aside from my personal scheming to make it into something more, there's also the fact that users and sysadmins eventually need to interact with systems written using Twisted and there are basically no resources for them to learn to manage said systems.

As much controversy as there is over exactly how good or bad our docs are, I think we can all agree that admin/user docs are in much worse shape than our developer docs (i.e. they are non-existant) :).

But more importantly...

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

I think that this is actually a better way to deal with most of our programmer-focused documentation.

Most importantly, the first rule here is very important: <http://jacobian.org/writing/great-documentation/what-to-write/>.  "Be quick.".  Good documentation writers frequently stress the importance of immediate gratification.  Good game designers will also tell you that you want to get a user engaged and experiencing success during the tutorial, before they really know how to play the game.  The immediate dopamine hit from a working 'twistd' command-line will carry the user through the slightly more confusing parts of getting their own code to work: it assures them that they can get Twisted to do _something_, which gives them immediate hope that maybe one day they can get Twisted to do what they want.

A corollary to this is that if it's going to fail, it can fail faster, and we all know that one should fail as fast as possible.  If the 'twistd' command-line doesn't even work, that lets the tutorial reader address configuration and installation issues much earlier on, rather than try to debug them as issues with their own code, they can just say, 'I ran this command and I got a traceback', which will get the attention of a Twisted maintainer more quickly because it's easier to diagnose something that's purely under our own control than a (potentially arbitrary, even if small) pile of new code.

I actually think that the inclusion of the 'twistd web' command-lines is one of the things that made the web-in-60-seconds tutorial series a big improvement over our previous web documentation :).

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

No argument here.  Le sigh.

> 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 _want_ people to show up on the tracker and actually report usability issues and missing functionality from the command-line tools.  It's still surprising to a lot of people, even very experienced twisted people, just how much functionality is exposed by those tools.  And if nobody knows the tools are there, then chances are they will remain a non-priority forever, as functional library issues will continue to get reported by the much wider audience that's actually using them.  Plus, on the bright side, the increasing prevalence of the use of cred and endpoint string-plugin APIs means that some of the twistd plugins are starting to become actually useful for things where they weren't before.  'twistd' web, in particular, also has RPYs, which almost turn it into a full-featured server; other servers should have similar application-level plugins.

(And as I finish writing this, I think: 'twistd web' could be _really_ pretty useful if it weren't such a pain to deploy a WSGI app using an RPY, thanks to threadpools etc.  We should add a utility function or something.  Anybody feel like writing a ticket?  I have heard references to '.wsgi' files, is that a thing we could support?)

-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20110201/3bbed048/attachment.html>