Re: [promises] Guidance on the usage of promises for API developers

Nice writing! Both the shorthand phrases and guidance look very useful for
writing Promise based specs.

I have only one comment on this section.
https://github.com/domenic/promises-unwrapping/blob/master/docs/writing-specifications-with-promises.md#maintain-a-normal-control-flow

I agree with your point in the first paragraph, but the suggested way looks
rather confusing. The asynchronous operation abstracted by Promises is well
described, but selling this convention (writing what usually happens later
before return without any annotation) to everywhere sounds too much, I
think. It's good to move "Return p" to the end of the steps. But how about
also keeping "do blah asynchronously" text?

1. Let p be a newly-created promise.
2. These steps will be run asynchronously.
  1. If blah, reject p with undefined.
  2. If blah, resolve p with foobar.
3. Return p.

Thanks