[Twisted-Python] Trial docs?
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
On 4/10/07, Terry Jones <terry@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
On 01:38 am, terry@jon.es wrote:
Within the last month, someone mentioned to me that Trial was one of the better-documented components of Twisted.
Terry, if I was the one who committed this terrible crime against you, I apologize. I hope that, if that was the case, it was simply a miscommunication and I had actually said something like "trial (ought to be) one of the better-documented components of Twisted". The best documentation I know of for trial right now (and the only thing I routinely consult) is "trial --help".
I guess we'll all agree that this could be improved.
Indeed.
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.
As the esteemed Mr. Lange already said, this email *was* very valuable. Thank you.
I'm happy to edit the wiki if one of you will fill in the X and Y's in the above.
What's your login name for trac? I think someone will need to give you edit permission, if they haven't already.
participants (3)
-
glyph＠divmod.com -
Jonathan Lange -
Terry Jones