[Twisted-Python] Task-based documentation started

[Kevin Horn]

On Tue, Feb 1, 2011 at 11:55 AM, Glyph Lefkowitz <glyph at twistedmatrix.com>wrote:

>
> 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?)
>
>
>
Agree pretty much 100% with everything Glyph said.  As I've been working on
the Sphinx conversion, I've read (or at least skimmed) pretty much every
piece of documentation Twisted provides.  And I've been surprised both by
things I never expected to see, and by the stuff that is glaringly missing.
Also that the man pages are almost totally divorced from the rest of the
docs.  Another thing I'd like to remedy.  I'm really hoping that both the
Sphinx changeover as well as the other recent attention to docs will make
the docs easier to use, and also highlight some of the arcane and strange
places in the various APIs.  I'm hoping some intrepid docs-author/editor
will be reading/writing along and go "Wait. What?  It works like what?  That
doesn't make any sense.   I'm filing a ticket, that needs to be fixed!"

Maybe I'm too optimistic, but I'd still like to see it.

Kevin Horn
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://twistedmatrix.com/pipermail/twisted-python/attachments/20110201/65d85774/attachment-0001.htm