I've incorporated most [1] of the feedback on-list into the latest draft [2]. It now includes an abstract, sections on when to use promises and when not to use them, and revised and reorganized guidance, shorthands, and examples sections.
I haven't gotten to fixing everything mentioned [3]; in particular the async algorithm-writing advice hasn't been fixed yet [4]. But I'd love another round of feedback and suggestions. I'm particularly interested in what people think of the new examples [5], `delay(ms)` and `validatedDelay(ms)`; I fleshed them out with more rigor and some JavaScript code illustrating the correspondence. (The others are still a bit crusty.) I'd also love to hear what other examples could be added to help illustrate interesting or important concepts. [1]: https://github.com/w3ctag/promises-guide/issues?page=1&state=closed [2]: https://github.com/w3ctag/promises-guide [3]: https://github.com/w3ctag/promises-guide/issues?page=1&state=open [4]: https://github.com/w3ctag/promises-guide/issues/7 [5]: https://github.com/w3ctag/promises-guide#examples -----Original Message----- From: Arthur Barstow [mailto:art.bars...@nokia.com] Sent: Tuesday, January 14, 2014 07:33 To: public-webapps Subject: [promises] Guidance on the usage of promises for API developers FYI. (If you want to followup, please reply on www-tag @ w3.org) -------- Original Message -------- Subject: Guidance on the usage of promises for API developers Resent-Date: Mon, 13 Jan 2014 22:50:19 +0000 Resent-From: <www-...@w3.org> Date: Mon, 13 Jan 2014 22:49:30 +0000 From: ext Domenic Denicola <dome...@domenicdenicola.com> To: www-...@w3.org <www-...@w3.org> In the past, the TAG has discussed producing a document on how to use promises in spec text. There's even a placeholder on GitHub [1]. In the process of writing the ES6 promises spec, I ended up producing such a document myself [2]. It feels like an OK start to me, with some great feedback from Marcos incorporated a month ago. I'd be happy to push this document forward as a more official TAG work product. Presumably we'd move it to its own repository and all that. But first, I'd love to solicit feedback from spec authors and readers on what's currently there, and what you think should be there. Is it clear? Is it useful? For those writing specs using promises, have they found its guidance helpful, or have they found other tips that would be good to include? Several of the "guidance" points were drawn from finding mistakes in existing drafts that use promises; are there more drafts we should review? Feedback much appreciated, either here, or as an issue on the spec repository where the document currently lives [3]. (Note that I'm mostly concerned with content for now; we can worry about formatting later.) [1]: https://github.com/w3ctag/promises-spec-text [2]: https://github.com/domenic/promises-unwrapping/blob/master/docs/writing-specifications-with-promises.md [3]: https://github.com/domenic/promises-unwrapping/issues/new
