Applying suggestions from openjournals/joss-reviews#93

doc/basics.adoc

@@ -9,7 +9,7 @@ Editor and IDE support for Golo is available for:
 - https://github.com/jponge/vim-golo[Vim]
 - https://github.com/k33g/sublime-golo[Sublime Text 2 & 3]
 - https://github.com/k33g/golo-storm[IntelliJ IDEA (syntax highthing)]
-- https://github.com/golo-lang/gldt[Eclipse] (contributed by Jeff Maury)
+- https://github.com/golo-lang/gldt[Eclipse] (initially contributed by Jeff Maury, currently outdated and seeking for new contributors)
 - https://github.com/golo-lang/golo-netbeans[Netbeans] (contributed by http://www.serli.com/[Serli])
 - https://atom.io/packages/golo-ide[Atom] (package golo-ide)
 - https://github.com/zyedidia/micro[Micro] (Gololang support for Micro is native)
@@ -232,8 +232,8 @@ function main = |args| {
 }
 ----
 
-NOTE: Each `golo` and `jar` files present in the script file's directory or the sub directories
-will be scaned.
+NOTE: Each `golo` and `jar` files present in the script file's directory or the sub directories will be scanned.
+This makes it easy to run scripts and have an automatic classpath for libraries, and automatically compile and load other Golo files.
 
 [source]
 ----

doc/pitfalls.adoc

@@ -80,3 +80,13 @@ println(foo)
 # Bad! foo is an integer!
 println(foo("abc"))
 ----
+
+=== Shebang scans sub-folders
+
+When running _shebang_ scripts, the sub-folders are being scanned for `.jar` and `.golo` files.
+This is useful for automatically:
+
+1. putting all third-party libraries into the classpath, and
+2. dynamically compiling and loading other Golo source files.
+
+Be aware that this may lead to surprising errors if you run code from, say, a clone of the Golo source code repository since it contains duplicated type and module definitions, as well as files from the test suite that have errors on purpose.