new topic: asynchronous programming about docs

[drewfish]

It occurred to me that there's another type of async programming: polling. (For example, startWork(); while (!resultsAvailable()) { do other stuff } results = getResults().) It's very uncommon in node.js programming and so would probably just confuse new users.

[drewfish]

Since we currently have neither the the callback topic, nor promises topic, I'll probably include a small placeholder description and links to guides on the internet. Once we have these topics we can revise this doc to leverage the topic docs to describe the material.

[chrisdickinson]

Sounds good! The outline seems a bit more like a topic doc than a guide doc — but it could go either way depending on how the document is written; either way, it would be a valuable addition!

[drewfish]

Hmmm... which do you think would best serve the community, topic or guide?

If this should be a guide, what might a guide outline look like?

[chrisdickinson]

Usually a guide has the reader build something — a little webserver, or CLI — and explains the concept it's trying to convey using examples from the readers experience with that code. Guides are great for introducing new concepts in a comfortable way, by letting the reader "simulate" the process of what development will be like using those concepts. Django's getting started guide is a great example of this, though it doesn't necessarily have to be aimed at beginners.

Guides aren't a great place for "deep dive" information, though — they have to link off to topic docs to handle anything that's fairly intricate. Pulling from Django again, in this tutorial it's noted that to continue the reader will have to have pip available. Instead of detailing how to get pip in the guide, it links to the other topic document.

Eventually / ideally we ought to have both a guide and a topic doc on this concept to help folks reason about async programming in Node.

[drewfish]

Got it, thanks. I think I was thinking more of a topic, so I'll attempt that.

[Trott]

Closing as this repository is dormant and likely to be archived soon. If this is still an issue, feel free to open it as an issue on the main node repository.