make the docs clearer

per https://github.com/omniti-labs/omnipitr/issues/15 by Greg Jastrab