Documentation improvements

[oremanj]

#7: our example doesn't actually work, due to a mypy bug
#6: provide an example that demonstrates correctly typed usage of channels, since the error that mypy provides if you drop the type variable is confusing