[Twisted-Python] Trial docs?

[Terry Jones]

Hi jml

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

Great. I also always find it useful to have outsiders and first-timers make
comments. It's probably impossible to look with fresh eyes at things you've
spent a ton of time working on. I know I can't do it - partly through lack
of time, energy, inclination :-)

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

OK, but that wiki page is your chance to say so, or say something.

| It's interesting that you didn't consider looking into Twisted's
| documentation to find out more about Trial.

>From the home page I go to http://twistedmatrix.com/trac/wiki/Documentation
and I don't see a link for Trial. Part of what's misleading here is that
there are explicit links for various projects, and Trial is listed as a
project on the page I just came from. So, a specific recommendation: add
Trial to the list of projects, and say "Trial is documented in the core
documentation" with a link.

Following your suggestion, I now click on Core Documentation. On the page I
land on, I immediately search for Trial, but there is no hit. Specific rec:
add the word Trial somewhere on this page so users and Google etc. can see
it.

But I do see a link called "Tips for writing tests for Twisted code". Is
that or is that not Trial documentation I wonder? The destination page is
howto/testing.html and at the top it does look like I've arrived at the
right place. Is that what you meant? But after a few sentences it does
degenerate into tips that are too advanced. Shouldn't someone tell me for
example what Twisted class I should subclass in making a test suite, before
telling me to leave the reactor (what reactor? thinks the newbie) as I
found it?

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

Can the default be changed to just search the wiki? Perhaps just on
searches from the main page? That looks like it would just be a matter of
dropping changeset=on and ticket=on from the URL.  I know, that's probably
a trac thing, but it might help.

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

Thanks. I'm old :-)  And on my machine:

    $ file /usr/bin/nroff
    /usr/bin/nroff: Bourne shell script text executable
    $ grep Emulate /usr/bin/nroff
    # Emulate nroff with groff.

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

Yes, that's part of it (see above about seeing Trial listed as a project
but then not seeing it under the projects on the main doc page).

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

So I did!  That's great, thanks. It's exactly the kind of doc I'd like to
be reading - nicely fomatted and giving confidence that it's clearly
machine generated (and therefore stands a chance of being up to date).

A link to that page would have really helped.

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

Me too. And the doc strings in the code are (relatively) pretty good.

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

And vice versa (much more of the vice versa, of course). So thanks back.

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

I'll make some interim cosmetic changes to the wiki if you like. (Where
interim has its usual meaning: will only be there for a couple of years...)

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

OK, thanks.

Terry