Let's make ClojureScript more approachable for beginners

[Andrey Bienkowski]

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://elm-lang.org has a big and obvious "Tutorial" button on its homepage

- 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:

- https://www.python.org has a REPL built into its homepage

- https://elm-lang.org has a big and obvious "Try" button

# 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

For some reason instead of following the common convention of --option=value the compiler (clj --main cljs.main) invents its own command line syntax based on the EDN. On top of that neither https://clojurescript.org/reference/repl-options nor https://clojurescript.org/reference/compiler-options nor https://clojurescript.org/reference/repl-and-main actually provides an example of specifying EDN on the command line. It currently just so happens that https://clojurescript.org/guides/quick-start does provide such an example, but only because it needed to document the workaround for the above mentioned bug. Also: in many places the extensible data notation is referred to by a cryptic 3-letter acronym EDN that probably has 300 different meanings. The acronym not being a link pointing to https://github.com/edn-format/edn does not help either. Also: edn-format.org is missing an HTTPS version.

# 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 first saw your documentation I saw a list of links on the left and a list of links on the right. It did not take me long to figure out that one is the table of contents for the current document and another is a list of links to other documents in the same section but it wasn't immediately obvious to me either. A https://readthedocs.org like format would be less confusing. Example: https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html

- 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

[Sergei Udris]

Did wonder about Reference/Guides myself. But at the end of the day, it's such a tiny detail, not a problem, the search engine serves the right page anyway. 

As of now, I'm not a contributor, only a mere user of the clojure ecosystem. But a happy one - given what a treat and gift this super powerful abstraction is.

Not going to pile up wisdom, just want to simply say: we are gifted an immutable lisp that is one language and reaches everywhere java and js do. And we are given core.async. So that outweighs any kind of learning curve/setup IMHO.

But yes, it's a bit less detailed. Well, I can only speak for myself - and I'm not complaining, because this kind of work (guides/tutorials) is tedious and ungrateful. And we are always kind of free to contribute/create nayhting that would make "getting into clojure" more cakewalk-y.

And another thought/observation: usually (and in my case) people discover clojure, when they are desperate, frustrated. And that happens after we - programmers -  go through some issues. Simply put, when we get to clojure, we already know java/js ecosystems/tools and are less dependent on a smooth entry point. But again, it does not mean things should not improve. Just an observation.

* [Deleted previous post to remove unnecessary profanity (one word change). Sorry, felt need to correct myself if possible. Will be more focused next time]

[Andrey Bienkowski]

> The REPL hangs on Linux

The patch for this bug have been available for over a year (https://clojure.atlassian.net/browse/CLJ-2493). I hope the maintainers eventually get around to merging it.

[Alex Miller]

I actually spent some time looking at this last month for whether to include in Clojure 1.10.2. While the patch does "work", I am somewhat undecided still about whether it's the best approach so I decided to wait until 1.11 to consider it more, but it is high on the list. Feel free to vote at https://ask.clojure.org/index.php/751/clojure-java-shell-sh-hangs-calling-xdg-open.

BTW, it's high on my list because it has votes on https://ask.clojure.org - please make your priorities known there, we're looking at vote counts! 

Alex

[Yehonathan Sharvit]

Hello!

I totally agree that allowing beginners to learn ClojureScript and experimenting with code in the browser bring a huge benefit and  will increase ClojureScript usage.

Klipse addresses this challenge by providing:

- An online ClojureScript repl: http://app.klipse.tech/

- A way to embed ClojureScript running snippet in a web page (blog posts, documentation etc..)

Several online ClojureScript tutorials leverage Klipse. Here are some examples:

1. Reagent deep dive http://timothypratley.blogspot.com/2017/01/reagent-deep-dive-part-1.html
2. How to write macros https://blog.klipse.tech/clojure/2016/05/05/macro-tutorial-3.html

[jdavid.e...@gmail.com]

Shameless self-promotion: here is a thing I did some years ago - http://langintro.com/cljsbook/