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.
not entirely sure yet what the actual examples will be...