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 sh*t. 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.
On Fri, Oct 9, 2020 at 5:24 PM Andrey Bienkowski <hexagonrecurs...@gmail.com> wrote: > 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 > <https://en.wikipedia.org/wiki/Structure_and_Interpretation_of_Computer_Programs> > and "On Lisp <https://en.wikipedia.org/wiki/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 <https://funcool.github.io/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 <https://github.com/edn-format/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 > <https://clojurescript.org/reference/repl-options#watch-fn> places > <https://clojurescript.org/reference/compiler-options#watch-fn> 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 > > -- > Note that posts from new members are moderated - please be patient with > your first post. > --- > You received this message because you are subscribed to the Google Groups > "ClojureScript" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to clojurescript+unsubscr...@googlegroups.com. > To view this discussion on the web visit > https://groups.google.com/d/msgid/clojurescript/eb0efca6-33d4-4321-a75b-ed1c35ba45efn%40googlegroups.com > <https://groups.google.com/d/msgid/clojurescript/eb0efca6-33d4-4321-a75b-ed1c35ba45efn%40googlegroups.com?utm_medium=email&utm_source=footer> > . > -- Note that posts from new members are moderated - please be patient with your first post. --- You received this message because you are subscribed to the Google Groups "ClojureScript" group. To unsubscribe from this group and stop receiving emails from it, send an email to clojurescript+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/clojurescript/CA%2Bq3MLw3L5PDi%2Bpbz7xvqLfqNGHwFt0qbMrnzu2QPcqkXY_EOw%40mail.gmail.com.
