pre-release review of readme file and readthedocs page

[jeremymanning]

@andrewheusser and @lucywowen when the documentation (readme file and readthedocs page) is all updated and live, can you ping me and i'll do an in-depth final review? (prior to that, please do a review yourselves to hopefully catch any remaining documentation issues.)

[jeremymanning]

my first pass through all documentation is complete. i think we're good for an initial release, but i'm going to open a new issue (not in this milestone) to do another pass through at some point and clean some things up further.