Feature/state machine design docs

@brutski @mdsol/hypermedia-team Please review and merge.

This PR adds documentation that describes analysis and example artifacts to generate to support producing API descriptor documents. It also fixes a few other documentation errors.
Here as well and elsewhere pointing to Sample eBooks doc.