Add section about moving to `six`.
Fix cross-references
Fix some typos
Fix example to one that actually fails.
Merge pull request #1481 from mdboom/docs/six-recommendations

Add information about moving to `six`