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.