docs suck. Need nicer docs please!

[Robert Collins]

In particular, some examples, a HOWTO and better pydocness.

[James Westby (james-w)]

In fact it seems the README lies quite a bit, for instance, it indicates that you should
override getResource and doesn't mention make, that TestCases will have self._attribute
set to the resource, whereas it seems to be self.attribute.

I imagine that they may be out of date, and while more docs would be great, the current
ones are incorrect, or at least misleading, and it would be great to fix that as a start.

Thanks,

James

[Robert Collins (lifeless)]

I certainly agree. I've just pushed out 0.2.3 with some known issues fixed, but the docs do still need this overhaul.