[Twisted-Python] Trial docs?

[Jonathan Lange]

On 4/10/07, Terry Jones <terry at jon.es> wrote:
> 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...

Hey Terry,

I'm sorry that finding Trial documentation has been such a chore for
you. I'd definitely like to make it more accessible so that Trial
itself can be more pleasant to use.

Thanks for writing such a full email too. This sort of thing really
helps me question why things are as they are, which is a good first
step to improving the 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.

This is an unfortunate situation. Part of the issue is that Trial is a
significantly-sized, relatively independent part of Twisted Core, so
it falls into something of an organisational nether-world.

That said, I doubt the project page for Twisted Core is significantly better.

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

You'll notice that the "DOCS" link appears on every page, outside of
the context. This links to Twisted's documentation.

It's interesting that you didn't consider looking into Twisted's
documentation to find out more about Trial. It seems we could do a
better job at communicating Twisted's structure here.

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

Note to self: review FAQ.

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

OK, now that is Trac's fault. You'll notice that the Trac search page
lets you uncheck the "Ticket" and "Changeset" boxes so that you can
just search the wiki. It's not particularly intuitive.

It's also sub-optimal that we require Twisted users to master Trac's
idiosyncrasies.

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

groff -man -Tascii doc/core/man/trial.1  | less

I'm guessing the confusion here is that you weren't expecting the
Trial docs to be under 'core'?

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

In your travels you missed on the part of Trial's documentation that
is actually much better than most of Twisted: the API docs.

http://twistedmatrix.com/documents/current/api/twisted.trial.html

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

Indeed!

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

Right. I think it's a good policy to explicitly recommend reading code
if there aren't any better docs.

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

Rest assured, this email is definitely valuable. So, although you may
have been able to do better stuff, you are certainly making my job
easier.

Thomas is working on a better Trial document which should solve some
of these problems. The presentation on the website is a separate, and
possibly more pressing issue, which I'll file a bug for.

In the interim, if you have any problems using Trial, you can (almost)
always contact me on IRC.

cheers,
jml