Enhanced documentation for each package about kit HOT 3 CLOSED

@peterbourgon do you think its worth creating an example README by hand first? Something we can all agree on and then seeing how we can use computers to re-generate it?

I like the idea of having examples that are verified by the test suite. This should help reduce the chances of README drift.

from kit.

I'd rather tackle it from the other angle: see what the tools can do, and then tweak it as necessary. I honestly don't care about many of the details, as long as we have a package overview, a rationale, and links to the example_xxx.go examples.

from kit.

I've pushed an overhaul to the documentation, focusing heavily on examples. Still some rough edges to smooth out, e.g. #107, but this can be considered done, I think.

from kit.