I gave another talk on this subject last night at the St. Louis OOSIG meeting. Not a huge crowd, as the announcement came a little late (that's my story and I'm sticking to it :)). Presentation went really well I thought, and I'm really getting my thoughts and ideas in focus around this subject. I do think there is a tool and a technique missing from my bag of tricks that would make life easier when using tests as docs.
There has got to be a way to navigate from a source method to the list of tests for that method. I believe that this map should be build by annotating the tests with the name(s) of the method(s) that it is exercising. And I believe that the documentation generators should build a map that lists all the methods of an application class as hotlinks. Choosing one of these hotlinks takes you to another page with a list of tests that go along with that method.
I think that would make life a lot easier when it came time to find out how to use a particular method.
Anyway, here is a link to the slides I used last night. As always, comments are appreciated.
-- bab