lihaoyi / hands-on-scala-js

Better documentation for Scala.js
142 stars 52 forks source link

`Stages` are referenced before they are explained #46

Open adamvoss opened 7 years ago

adamvoss commented 7 years ago

The Stages begins with:

Let us recap the three different stages of execution, and what they mean.

The stages themselves have not been explicitly explained prior to that point though they were referred to in regards to selection of execution environment. Already somewhat fatigued, my eyes started to glaze over when I first saw mention of them when talking about execution environment.

I think the tutorial could be stronger if stages were more explicitly addressed before referencing them in regards to choosing the execution environment. Perhaps this could be done by introducing their names explicitly under the various commands (assuming they are directly utilize by the commands, which I presume they are). Alternatively, Headless Runtimes could be moved after Stages and the content under The run Command that pertains to choosing the runtime could be integrated under Headless Runtimes.