If you have a suggestion for warnings please open an issue https://github.com/petkaantonov/bluebird/issues
If you want to contribute we'd love docs contributions as you clearly have good technical writing. Here are the 3.0 docs (currently under work) https://github.com/petkaantonov/bluebird/tree/3.0docs/docs/d... any help with pages that explain promises conceptually (anti patterns page etc) would be highly appreciated.
That's exactly what I meant when I said it's better for your tools to warn you, rather than trying to read and understand some lengthy article. :)
BTW for PouchDB, we use bluebird in Node and lie in the browser, and bluebird has been truly indispensable for debugging. Looking forward to it getting even better!