[Twisted-Python] Trial docs?

[Terry Jones]

Within the last month, someone mentioned to me that Trial was one of the
better-documented components of Twisted.

I just decided to write a couple of quick unit tests for talking to a
Twisted web2 server. No problem, I thought, I'll just dig up that Trial
documentation...

  - Go to http://twistedmatrix.com/trac/ and click on Twisted Projects.
    Click on Twisted Trial.  There's nothing there, just a link to thoughts
    on future dev and a link into the tracker.

  - I notice a DOCS link at the top right. Non-obvious, but that must be
    it. But no, this takes me to the top of the Twisted documentation and I
    see no link for Trial.

  - But there's a FAQ, so I go there. There's one mention of trial, but
    it's not to do with documentation.

  - Google "twisted trial documentation". There are some one year old links
    to a page talking about how to improve the Trial documentation via
    chatting in IRC. I scan the first page of hits - none of them lead me
    back into the twisted site.

  - Back on the Twisted site I look for a search box, and there is one.
    Yay. Enter 'trial' and I get back 76+ pages of hits, the first of which
    is virtually all trac issue links, plus some mention of monkey
    patching, which doesn't sound relevant.

  - Well, I have the Twisted tree checked out, so I'll look there. Nothing.

  - Maybe there's some documentation in the tarball? Back to the Twisted
    home page, download, untar, find, nroff -man, etc. There's something,
    but just invocation options.

  - I run trial at the command line. More invocation options.


I guess we'll all agree that this could be improved.

I don't mind reading code. I wish someone would just tell me up front that
that's what I should do. Or is it? I really don't know in this case. I just
know that if there is any documentation for Trial it's pretty well hidden.

Just doing the above and now sending this mail (with the aim of improving
things for others) has taken me probably 45 minutes, on top of which my
fingers now ache. I wish I could have used all these keystrokes to do other
stuff.

I think the Trial page at http://twistedmatrix.com/trac/wiki/TwistedTrial
should be changed to say something like this:

  Documentation:

  Trial is currently undocumented.

  However, you can find some information by

    - Studying the example usage of trial in X project found in the Y
      directory of the Twisted tarball (or wherever).
    - Reading the trial manpage in the Twisted tarball, which will show you
      trial command line invocation arguments.
    - Reading the source code, which you can find in the Twisted tarball at
      X, or which you can see in the tracker at Y.

  Please feel free to contribute, etc.

I'm happy to edit the wiki if one of you will fill in the X and Y's in the
above.

Terry