Ahodges/doc/doc1117

@mulby , @shnayder , @WatsonEmily , @mhoeber , @catong , @srpearce , @stroilova , @dsjen please review. I do not yet have images to illustrate my examples, but otherwise ready.
yes, and they will be added in subsequent PRs