Rewordings and corrections to Promise Basics #418

davegregg · 2018-03-27T18:16:40Z

Corrected a few things that seem to be leftovers from inaccurate translation.
Reworded several things to more natural-sounding English.
Added some more clarification in a few places.
Nearly replaced the "Handlers of .then/.catch are always asynchronous" section in an effort to make it more comprehensible for people who may be new to asynchronous operations.

iliakan

The topic is subtle and important.

iliakan · 2018-03-31T19:35:47Z

6-async/02-promise-basics/article.md

-3. A *promise* is a special JavaScript object that links them together. That's a "list". The producing code creates it and gives to everyone, so that they can subscribe for the result.
+1. A "producing code" that does something and takes time. For instance, the code loads a remote script. That's a "singer".
+2. A "consuming code" that wants the result of the "producing code" once it's ready. Many functions in your "consuming code" may need that result. These are "fans".
+3. A *promise* is a special JavaScript object that links the "producing code" and the "consuming code" together. In terms of our analogy: this is the "subscription list". The "producing code" takes the time it needs to produce the promised result, and the "promise" makes it available to all of the subscribed code when it's ready.


Please reread the last sentence. Is it ok?

Also, maybe:

A "consuming code" that wants the result of the "producing code" once it's ready. Many functions may need the result. These are "fans".

Sorry, just getting back to this PR. Slightly reworded.

iliakan · 2018-03-31T19:37:32Z

6-async/02-promise-basics/article.md

 ```

-The function passed to `new Promise` is called *executor*. When the promise is created, it's called automatically. It contains the producing code, that should eventually finish with a result. In terms of the analogy above, the executor is a "singer".
+The function passed to `new Promise` is called the *executor*. When the promise is created, this executor function is called (run) automatically. It contains the producing code, that should eventually produce a result. In terms of the analogy above: the executor is the "singer".


Maybe remove (run)?

rephrased to (or, run) for clarification

iliakan · 2018-03-31T19:39:46Z

6-async/02-promise-basics/article.md

-1. The executor is called automatically and immediately (by `new Promise`).
-2. The executor receives two arguments: `resolve` and `reject` -- these functions come from JavaScript engine. We don't need to create them. Instead the executor should call them when ready.
+1. The executor is called automatically and immediately (by the `new Promise`).
+2. The executor receives two arguments: `resolve` and `reject` — these functions are pre-defined. We don't need to create them. Instead, we should write the executor to call them when ready.


The word "pre-defined" is not as obvious as "come from JavaScript engine", how you think? I mean, the reader should understand that they are come from by Javascript itself.

Compromise: "these functions are pre-defined by the JavaScript engine. So we don't need to create them."

iliakan · 2018-03-31T19:42:24Z

6-async/02-promise-basics/article.md

 ```

-The idea is that a job done by the executor may have only one result or an error. In programming, there exist other data structures that allow many "flowing" results, for instance streams and queues. They have their own advantages and disadvantages versus promises. They are not supported by JavaScript core and lack certain language features that promises provide, we don't cover them here to concentrate on promises.
+The idea is that a job done by the executor may have only one result or an error. (If you are familiar with other languages, you might be aware of data structures which allow many "flowing" results, like streams and queues. They have their own advantages and disadvantages as compared with Promises. But as they are not supported by the JavaScript core, we won't be covering them.)


Words about "familiarity with other languages" here are not terribly precise. Such structures exist in JS as well, and are quite well-known (just maybe not know to the reader yet). No need to mention other languages here.

Removed the parenthetical. Thanks!

iliakan · 2018-03-31T19:43:38Z

6-async/02-promise-basics/article.md

 ```

-For instance, it happens when we start to do a job and then see that everything has already been done. Technically that's fine: we have a resolved promise right now.
+For instance, it might happen when we start to do a job but then see that everything has already been completed. That is fine: we have a resolved Promise immediately.


Maybe "it might happen that we start to do a job..."?

Either works in this case. I rephrased this way: For instance, this might happen when we start to do a job...

iliakan · 2018-03-31T19:45:10Z

6-async/02-promise-basics/article.md

 ```

-If we're interested only in successful completions, then we can provide only one argument to `.then`:
+If we're interested only in successful Promises, then we can provide only one function argument to `.then`:


Why the change completions -> Promises? Here we're talking about promise results.

Reverted to "completions".

iliakan · 2018-03-31T19:45:51Z

6-async/02-promise-basics/article.md

 ```

-If we're interested only in errors, then we can use `.then(null, function)` or an "alias" to it: `.catch(function)`
+If we're interested only in errors, then we can use `.catch(errorHandlingFunction)`, which is just like doing `.then(null, errorHandlingFunction)`.


...which is exactly the same, not "just like".

Clarified with your wording

iliakan · 2018-03-31T19:48:11Z

6-async/02-promise-basics/article.md

+````smart header="Handlers of `.then`/`.catch` are always asynchronous"
+Even when the Promise is immediately resolved, code which occurs on lines below your `.then`/`.catch` can still run first. When the JavaScript engine sees your Promise, it will not only run the executor (the "producing code"), it will also go ahead and start executing code which occurs after your Promise and its `.then`/`.catch` calls.
+
+So, when it is time for the function passed to `.then`/`.catch` to execute (nearly immediately in the case of an immediately-resolved Promise), the JavaScript engine puts it into an internal execution queue which will then already have items to be run.


The new explanation is hard to understand for the person not familiar with the topic already.

iliakan · 2018-03-31T19:48:58Z

6-async/02-promise-basics/article.md

+So, when it is time for the function passed to `.then`/`.catch` to execute (nearly immediately in the case of an immediately-resolved Promise), the JavaScript engine puts it into an internal execution queue which will then already have items to be run.

-In other words, when `.then(handler)` is going to trigger, it does something like `setTimeout(handler, 0)` instead.
+The JavaScript engine is trying to do as many things at virtually the same time as possible. Everything is racing to get done. So, in the example code below, behind the scenes, you can imagine that the events might occur in this order:


"The JavaScript engine is trying to do as many things at virtually the same time as possible" - that's confusing. May seem like we're talking about multithreading, but we're not.

…al-en

iliakan · 2018-06-06T20:24:02Z

Is this PR dead?

davegregg · 2018-06-06T22:17:26Z

Sorry, I've had to suddenly write a lot more curriculum for my code school, so I put this off, but I'm mostly done with the revision. Just have to finish the last big part, which I will do this weekend.

Merge branch 'master' of https://github.com/iliakan/javascript-tutorial-en

davegregg · 2018-06-11T18:52:22Z

Alright, I have attempted to address all of your concerns. Please see the latest state of the PR.

iliakan · 2018-06-11T20:59:31Z

Great stuff, @davegregg
By the way, are you interested to learn git?

I have a great screencast about it, much better than all I've seen (ok, I hope so, people can judge), it is being be translated to English, maybe you could review the text or even voice the English version?

davegregg · 2018-06-12T12:13:08Z

Yeah, I'd be up for helping with that. I'm pretty comfortable with git, so it won't be an issue.

iliakan · 2018-06-12T12:37:49Z

I added you as a collaborator.
As of now, the 1st issue text is ready: https://github.com/iliakan/git-screencast/blob/master/s1/e1-en.md

Please fix wherever you think is better. Also if you see any mistakes about git (hope there won't be any), let me know, so I can fix those in the English version.

P.S. Do you have Mac?

davegregg · 2018-06-12T15:07:39Z

I do have a Mac. I might actually want to enlist the aid of a student of mine. It would be a good learning opportunity for them, and I will proofread the finished product when they are done. Would that work for you?

iliakan · 2018-06-12T15:48:18Z

Hi,

Thank you very much for your wish to participate.

There are three parts here:

Review the translation to ensure good English (needs only native English).
Check the text to ensure correctness, just in case (needs good Git knowledge, but a student may be ok too, they can signal if an explanation is not clear and learn Git in the process)
Voice the English version (may require a Mac, cause the screencast is written using Mac-only software, and normal/good English diction).

All that can be done by different people or by the same person.

davegregg · 2018-06-12T19:49:07Z

Alright, let me loop in Jake (@jakerjohnson94) -- can you add him to the git screencast project? -- as I think he could do a good job with helping to ensure the correctness and naturalness of the English text. When that's done, I'll decide who will help record the English version. I'm assuming the English version will be just audio narration that will be overlayed on top of the video you've already taken?

iliakan · 2018-06-13T08:34:51Z

Here's the repo: https://github.com/iliakan/git-screencast

I added Readme about the translation process.

davegregg · 2018-06-19T01:54:52Z

I've started my student on the process of proofreading and we'll get back with you

Issue javascript-tutorial#418

Rewordings and corrections to Promise Basics

ae57b66

iliakan requested changes Mar 31, 2018

View reviewed changes

davegregg added 3 commits April 9, 2018 12:22

Merge branch 'master' of https://github.com/iliakan/javascript-tutori…

ffcfda0

…al-en

Merge branch 'master' of https://github.com/iliakan/javascript-tutori…

cb806aa

…al-en

PR comment corrections, minus last two

6f446cc

davegregg added 2 commits June 11, 2018 14:35

Update from source

26ec750

Merge branch 'master' of https://github.com/iliakan/javascript-tutorial-en

Attempt to fix last two correction requests by iliakan

dfa4451

iliakan merged commit 482ec27 into javascript-tutorial:master Jun 12, 2018

azmo1213 pushed a commit to azmo1213/en.javascript.info that referenced this pull request Mar 14, 2023

Clarify a paragraph in exercise 4.4

755a023

Issue javascript-tutorial#418

Rewordings and corrections to Promise Basics #418

Rewordings and corrections to Promise Basics #418

Uh oh!

Conversation

davegregg commented Mar 27, 2018

Uh oh!

iliakan left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

iliakan commented Jun 6, 2018

Uh oh!

davegregg commented Jun 6, 2018

Uh oh!

davegregg commented Jun 11, 2018

Uh oh!

iliakan commented Jun 11, 2018

Uh oh!

davegregg commented Jun 12, 2018

Uh oh!

iliakan commented Jun 12, 2018

Uh oh!

davegregg commented Jun 12, 2018

Uh oh!

iliakan commented Jun 12, 2018

Uh oh!

davegregg commented Jun 12, 2018

Uh oh!

iliakan commented Jun 13, 2018

Uh oh!

davegregg commented Jun 19, 2018

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants