Maintaining Up To Date Documentation

[mgattozzi]

We recently ran into a problem on #177 where we found out the README was out of date. This was made an issue in #179 and resolved with #180. However, this brings up some questions about maintaining documentation. There is precedence in the language to maintain documentation for things. I wanted to open up discussion on maintaining docs within the repository so we can maintain the quality of them, make it easy for new people to contribute, and the best way to go about this.

Here are a few ideas I had:

1. We already have warn for missing docs and while this makes it easy to develop we should also make an effort to check the Travis logs to make sure the PR hasn't added extra warnings at all.
2. Developing a reviewer checklist of things that should be checked that not only affect the documentation but also other aspects of the code base. For instance in Update README.md #180 how rustdoc works was updated to reflect the fact we don't use the json-api crate anymore. In the future one of these items could be to check that if the PR affects the README or other out of code documentation, that it too is updated (like examples).

Thoughts? Better ideas? Maybe not these or something similar?

cc/ @euclio and @steveklabnik