Issue with Scala.js documentation

Documentation
1

After battling with Scala.js 1.3.0 for an hour or more, I am still very disappointed how brittle and fragile the whole project is. Every single time I visit this project, I waste so much time following abundant and abstruse documentation, poorly tested examples, and having to go to StackOverflow for help. Once I got it running, the results are very disappointing

sbt:Scala.js Tutorial> run
[warn] There may be incompatibilities among your library dependencies; run 'evicted' to see detailed eviction warnings.
[info] Compiling 1 Scala source to C:\Users\ERIC\Documents\git\scalajs-tutorial\target\scala-2.13\classes ...
[info] Fast optimizing C:\Users\ERIC\Documents\git\scalajs-tutorial\target\scala-2.13\scala-js-tutorial-fastopt
[info] Running tutorial.webapp.TutorialApp. Hit any key to interrupt.
[success] Total time: 8 s, completed Oct. 16, 2020, 11:05:51 a.m.

Note the absence of Hello world! as promised in http://www.scala-js.org/doc/tutorial/basic/

While Scala.js is a really great idea, so long as it’s always released as ‘hacker quality’ and never ‘commercial quality’, it is really hard to invest in it.

It would really be nice someday to see Scala.js 2.x.y that is of Commercial Quality, and not a bottomless pit of surprises, frustration, and disappointment…

2

This works for me in about 3 minutes.

The tutorial lists the following build.sbt:

enablePlugins(ScalaJSPlugin)

name := "Scala.js Tutorial"
scalaVersion := "2.13.1" // or any other Scala version >= 2.11.12

// This is an application with a main method
scalaJSUseMainModuleInitializer := true

is that the same for you?

1 Like
3

This is what came in the build.sbt file from GitHub

enablePlugins(ScalaJSPlugin)

name := "Scala.js Tutorial"
scalaVersion := "2.13.3"

// This is an application with a main method
scalaJSUseMainModuleInitializer := true

libraryDependencies += "org.scala-js" %%% "scalajs-dom" % "1.1.0"

// Add support for the DOM in `run` and `test`
jsEnv := new org.scalajs.jsenv.jsdomnodejs.JSDOMNodeJSEnv()

// uTest settings
libraryDependencies += "com.lihaoyi" %%% "utest" % "0.7.4" % "test"
testFrameworks += new TestFramework("utest.runner.Framework")
4

Okay, I was finally able to get things working. The documentation is very bad. I would offer to improve it, but somehow I don’t think there is any desire to improve it since Martin is bragging it only took him 3 minutes and is happy with only hackers playing with it…

5

Can you share what went wrong, please? Even if you don’t plan to submit a documentation improvement yourself, perhaps someone else will step up and do it.

That is false, and it’s also presumptuous and unkind.

Please keep the Scala Code of Conduct (The Scala Code of Conduct | The Scala Programming Language) in mind when posting. You’re obviously frustrated, but that doesn’t make it okay to lash out at people like this.

6

Why is this topic hidden from main page, i.e. from https://users.scala-lang.org/ ? Or is it just on my computer? It’s only visible under https://users.scala-lang.org/c/documentation/12 here.

Update:
OK, after replying it’s visible to me, but it still seems weird as in unlogged mode it’s still back to that hidden state.

7

That build file doesn’t work for me, it fails with

build.sbt:12: error: object jsdomnodejs is not a member of package org.scalajs.jsenv
jsEnv := new org.scalajs.jsenv.jsdomnodejs.JSDOMNodeJSEnv()

I followed the tutorial at https://www.scala-js.org/doc/tutorial/basic/ which doesn’t include that line. Which tutorial did you follow, so that I can see if I can reproduce your usecase?

My name, by the way, isn’t Martin, and I really dislike your characterization of me “bragging” that following the tutorial I linked takes longer than 3 minutes, that I’m favoring “hackers” over other users for whom it takes hours to follow that tutorial.

10

I don’t know what’s happening. I don’t see anything in the admin tools that explains it. I tried to unlist it and list it again, but that did not change anything.

If anyone is expert in Discourse tools and has an idea, I’m all ears.

11

It looks like the issue in on category level. On main page (https://users.scala-lang.org/) is see only one thread from “Documentation” category (https://users.scala-lang.org/c/documentation/12) i.e. the current one (as I was already guessing - it’s probably only because I’ve replied to it previously).

12

First of all, I agree that my comment “somehow I don’t think there is any desire to improve it” was inappropriate, so I apologize.

However, Martin’s comment “This works for me in about 3 minutes.” was dismissive, invalidating, and passive aggressive, so why doesn’t anyone call him out? I was genuinely trying to explain a problem, and for someone to just say “well it works for me” presumes there is something wrong with me and not the product. I see this kind of comment a lot in support forums. Basically, I was overreacting to his insensitivity and poor etiquette.

  1. I don’t know how to get Hello World! to print, which is very frustrating because my assumption is, ‘this should just work’ but it doesn’t
    • Along the way, it failed because the section on “Supporting the DOM” comes after the section on “HelloWorld Application”, where it should come before.
      • I had to go to StackOverflow for a solution.
      • There is an inherent problem with so much documentation, because it just does not get tested well.
      • This is even more problematic with ‘Getting Started’ documentation, where people just want to see something work correctly first, then learn the product.
      • This project would be better if there were more automation to set up the environment.
        Human being do not follow manual processes well, and developers do not test documentation well.
      • Automation is more testable.
    • In the end, it seems to display some text, but it disappears so quickly, I cannot tell what it is displaying.
  2. My solution was to select the scalajs-tutorial-fastopt.html and just open it in a web browser.
    • This works, and is much more satisfying than Hello World!
    • The documentation should present this before sbt run because
      • it clearly works better than sbt run
      • It really is the main point of Scala.js, that a JavaScript file is created that can be sourced in an HTML file

I would be happy to help with the documentation, but I need to know that my proposed changes are acceptable, because they are likely controversial, and I don’t want to waste my time.

13

I apologize for getting your name wrong. What should I call you? Martijn ? The ‘j’ is easy to miss.

I apologize for claiming you were “bragging.” What I should have said was that your comment was dismissive, insensitive, and passive aggressive, which is why I forgot my manners and responded inappropriately. When someone is asking for help, do you not understand how comments like “This works for me in about 3 minutes” are unhelpful, and presumes the problem lies with the person reporting the problem and not the product?

Regarding “hackers,” what I was expressing was a difference between polished commercial quality product, and unpolished research quality product. I did not mean to imply that you were ‘favoring “hackers”’ only that not enough effort has been spent on polishing the project. I genuinely want to see Scala.js succeed, but we have different opinions on issues of quality, polish, and commercial vs research.

I was following (http://www.scala-js.org/doc/tutorial/basic/) which links to (https://github.com/scala-js/scalajs-tutorial) but the two things are not in sync. This makes it frustrating for people getting started, when the documented steps are not really tested well.

14

I didn’t see anyone asking for help. I saw someone dismissing the scala-js project as something not to be taken seriously for “real” programmers, just for hacker kids playing with toys. All of that based on claiming the excellent, very complete and step by step hello world tutorial takes a reasonable programmer an unreasonable amount of time and effort to make sense of.

15

@martijnhoekstra

I was implicitly asking for help “Issues with Scala.js documentation” but I was also explicitly being critical. I should have been more explicit around asking for help.

However,

I saw someone dismissing the scala-js project as something not to be taken seriously for “real” programmers, just for hacker kids playing with toys.

could not be further from the truth, so now you are just projecting your emotions, around criticism, onto how you interpret my words. I was not dismissing it, because I also said

While Scala.js is a really great idea,…
It would really be nice someday to see Scala.js 2.x.y that is of Commercial Quality,…

These are not dismissive statements, rather they are very acknowledging and validating. However, I should not have used the term ‘hacker’ as it seems to evoke a strong knee-jerk reaction. But the reality is, Scala.js is not commercial quality yet, it is ‘research quality.’ For people in the research community that is fine, but for people in the commercial community, who are assessing technologies, it is hard to invest in some technologies and products when they are so complex, fragile, brittle, and difficult to get working. I spent my time in grad-school, I had my fun, but now I work in the commercial world.

Perhaps what the commercial industry really needs is a Kotlin.js, that puts more emphasis on commercial applications.

I am genuinely trying to be helpful here, but so long as you are overly sensitive to constructive criticism, we are not going to agree on much at all. I have apologized for my sins in this conversation, but you are completely unable to even see your sins, let alone ever apologize…

16

We’re going to have to agree to disagree on that.

17

@martijnhoekstra

At least we can finally agree on something :wink:

1 Like
18

OK, I’ll try to answer without getting hung up too much about the tone of most messages in this discussion. I typically don’t tolerate that much.

Do I understand correctly that the following happened:

  1. You found the repository https://github.com/scala-js/scalajs-tutorial, either through a search or from the basic tutorial
  2. You cloned that repository (but you did not checkout any particular commit)
  3. You tried to execute the run command because that’s what the tutorial told you to do in Step 1
  4. And things went bad from there (the jsdom issue, the “not displaying Hello World!” issue, etc.)

Assuming my understanding above is correct, here is why things did not work:

  • The repository for the tutorial is not meant to be used at the last commit from the beginning. Its commits follow the various Steps of the tutorial, and at each step the reader can either do the coding themselves, or checkout the relevant commit from the tutorial repo.
  • The above is announced in the very first paragraph of the basic tutorial (the same paragraph that links to the repo), although it is probably not made clear enough.
  • If we checkout the Step 1 commit from the tutorial repo, run works out of the box, without installing jsdom, and does display “Hello World!” on the console.
  • jsdom is only required when we checkout a later Step, at which point we have reached the part of the tutorial that tells to install jsdom.
  • I do test the process that we expect the reader to follow with every single release of Scala.js. We simply did not expect the above alternative process to happen in the first place. Our expectations were clearly wrong, but please stop accusing us of not testing our documentation.

What we’ve done since your first message:

  • We already added a sentence in the Prerequisites section telling about jsdom, that it will be needed later in the tutorial.

What could we do better to prevent the reader from trying to run things at the last Step of the repo while still at the beginning of the tutorial?

  • Should we put in the readme of each Step the commands that are expected to be used at that step?
  • Should we put in the readme that the reader should checkout commits in sync with the tutorial?
  • Should we do something completely different?
3 Likes
19

I don’t see clear instructions about how to clone the repository at the first commit and groll it forward. Is the repository meant to be used at all? Or is it just there as a reference, so that at any point someone following the tutorial can compare their code with the corresponding commit to see if they followed the instructions correctly? (This could be clarified in the tutorial.)

Either way it would be useful to have tags on each commit, like 1.x-step2 etc. Then someone can git clone -b 1.x-step1, or easily pull up the repo at step 3 in the GitHub UI.

The readme at head could definitely be made clear. Something to the effect of “this is what you should have if you followed [url] all the way through.”

You could update the readme similarly at each step, that might make it slightly less confusing for someone jumping around via the github UI.