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.
it's how edX computes them, not any external agent. Will work on the passive though!