Comments on design doc

I've put in some comments, in *italics* and tagged [colin], mostly around harmonizing the design of this SDK with the design of our two clearest existing SDKs - JavaScript and Unity.
Updated recommendations

I just found the mail that Bo circulated explaining the dialog situation, and I have more specific recommendations based on that.
clarifying change

Split two suggestions into their own paragraphs.
Merge pull request #542 from ccreitz/patch-1

Comments on design doc