Hi. I am new to ClojureScript. Here is my story so far. It highlights the unnecessary hurdles a new ClojureScript programmer has to overcome. I hope this helps make the ClojureScript better for everyone.
After reading
SICP and "
On Lisp" I am quite excited about lisp especially about lisp macros. The web is a very attractive platform to develop for. One day I set out to find an intersection of the two. A quick search returned a number of options and ClojureScript was one of them.
# Finding a tutorial
Every Lisp dialect is somewhat different from the rest and I had no prior experience with Clojure. How does one pick up a new programming language? I needed to find some kind of tutorial or introductory book. Something that would at the very least teach me the syntax and semantics of the language, the builtins and essential parts of the standard library. Ideally it would also teach me some common idioms. I tried to find a link to such a book/tutorial on the
https://clojurescript.org website, but failed. There is a prominently displayed "Get Started!" button, but it currently points to a page that teaches you how to install ClojureScript and, for some reason, how to do "Production Builds", but does not even cover the entire syntax of ClojureScript. Nor does it contain links to more complete introductory materials. I did eventually discover the amazing
ClojureScript Unraveled. Only later did I find out that the link was there all along, but it was buried where I would have never guessed to look: the "community" tab of the
https://clojurescript.org website. When I think "tutorial" I don't think "community", when I read "community" I don't expect to find a tutorial there.
Some examples for comparison:
-
https://www.haskell.org has an interactive tutorial built into its homepage. After you chew through it, the tutorial suggests you look in the "Documentation" section of the website that contains links to books, courses, tutorials etc.
# Finding an online REPL
OK I found a tutorial. To follow it I want to be able to actually type some code and see it print some output. I personally find it more convenient at this stage of learning a new language to use an online REPL rather than trying to figure out how to install the interpreter or the compiler locally. Even if installing is as simple as downloading and unpacking a tar or executing a bash script I still prefer an online REPL. I again struggled to find a link to an online REPL from the
https://clojurescript.org website because it was also hidden on the "Community" tab. Also: out of the 3 REPLs advertised there only one (
https://clojurescript.io) has an HTTPS version.
Some examples for comparison:
# Installing the compiler
OK I learned a bit of Clojure, I experimented a bit now I want to start developing in it. To do that I need to install the compiler on my machine. At this point I'm looking for links that say "install" or "download". Where do I find the installation instructions? "Get Started!", obviously.
# The REPL hangs on Linux
A little bit about my system: Linux+Firefox. It turns out that there is a known bug that causes the REPL to hang under this configuration. I was following the "Get Started!" tutorial. When I executed "clj --main cljs.main --compile hello-world.core --repl" I expected to see "Hello world!" printed in my terminal, but instead I saw something that looked like a REPL prompt but was completely unresponsive. The bug is even documented in the tutorial, but in a manner that took me an embarrassingly long time to find. Usually when a step in a tutorial fails the steps that follow it are irrelevant until you can figure out what went wrong so I did not continue to read the tutorial. The workaround for this bug is documented almost an entire page below the failing step. The workaround is also not visually highlighted - easily overlooked when skimming.
# It is hard to figure out the REPL and compiler options
# Specifying :watch-fn on the command line results in a confusing error
I specified --compile-opts '{:watch "src" :watch-fn (fn [] (println "built!"))}' on the command line and expected to see it print "built!" every time my source is rebuilt. Someone more savvy in how EDN works would know that this won't work, but to me this wasn't obvious until I tried it. Nothing was printed on the command line. It did not print "built!". It did not print any error messages. Luckily it did say: "compilation log available at: out/watch.log". Opening this file gave me a hint as to what went wrong: "java.lang.ClassCastException: clojure.lang.PersistentList cannot be cast to clojure.lang.IFn" but the error message could certainly be much more newbie-friendly. Out of the
two places where watch-fn is documented only one mentions "cljs.build.api/watch", but even then it does not actually link to
https://cljs.github.io/api/compiler/cljs.build.api/#watch leaving me to wander what "cljs.build.api/watch" means. Is it a file? Is it a command line tool? Apparently it is an API. How was I supposed to figure that out?
# Hot reload
"Why was I messing with compiler options and :watch-fn?" you might ask. What I actually wanted was hot reload. When I looked at the documentation for :watch-fn it looked to me as if the compiler already provides the hot reload functionality and no 3rd-party tools are necessary. Someone who knows a little bit about the compiler internals would know that :watch-fn is executed in the compiler instead of being executed in the context of my code, but this is not obvious from the documentation provided on
https://clojurescript.org. I did eventually figure out that I do have to install an additional 3rd-party tool to get hot reload and went with
https://figwheel.org.
# Reference/Guides split
A number of miscellaneous documentation topics on
https://clojurescript.org are split into two sections "Reference" and "Guides". Perhaps there is some deep wisdom to which documentation pages belong where but so far it eludes me and when I have a question I have to look in both sections. Perhaps merging them into one and naming it "Documentation" would be better.
# Miscellaneous nitpicks
- When I scroll the page the table of contents and links to other documentation topics scroll out of view instead of staying on the screen.
- The landing pages for "Reference" and for "Tools" duplicate the list of documentation topics in that section, but not one-to-one.
https://clojurescript.org/reference/documentation has a heading labeled "API Documentation" but this heading is not duplicated in the links on the left of the page. The "Tools" section of your website has pages for lein-cljsbuild and lein-figwheel, but there are no corresponding links on
https://clojurescript.org/tools/tools
-- Andrey Bienkowski