Context Free Documentation

[Eric Kolotyluk]

First off, I am not trying to troll anyone, I am merely trying to understand some common practices that lead to my ongoing frustrations with using Scala.

I have been using Scala since 2005, and I am pretty good with it, but have a lot of difficulty with much, but not all, Scala documentation. For example at

Scala.js Interoperability

the page displays what looks like some simple Scala.js code, but it lacks the necessary context to copy/paste into IntelliJ and have it actually compile and run.

It would be far more useful from an educational, instructional, tutorial perspective to add the necessary context to easily copy/paste something useful into IntelliJ.

1. Provide an expandable document element that provides the full context
2. Provide a link to some GitHub examples.
   • In fact, I see this practiced a lot in documentation where the author really wants their readers to understand and use their products.
     

In particular, why does this code fragment omit all of the 'import' statements that provide the necessary context?

As an author myself, I do strive to provide context to my writing, but I am curious why other authors seem motivated to reduce or eliminate context?

Eventually I did figure out how to make this code work, but it would have been a lot less frustrating if the documentation provided the necessary context which was a few essential 'import' statements. Why were these deemed unnecessary in the documentation?

I have tried to use Scala.js many times in the past, but I have always walked away when my frustration with the documentation exceeds a certain threshold.