
ClojureScript beginners' home page - jiyinyiyong
http://clojure-script.org/
======
aaroniba
You might think from the URL or logo that this is some kind of official
ClojureScript page, but it's not. The official page is clojurescript.org (no
hyphen).

I don't speak in any official way for ClojureScript, but as an enthusiast, I
wish this author had chosen a different URL to make that more clear.

Other ideas to mitigate the confusion: using a different logo in the corner;
prefixing the html <title> with "unofficial"; and adding a more prominent link
to clojurescript.org titled "Official ClojureScript Page".

~~~
jiyinyiyong
Well, you may need this one
[https://www.reddit.com/r/Clojure/comments/8anepx/a_fake_home...](https://www.reddit.com/r/Clojure/comments/8anepx/a_fake_home_page_for_clojurescript/)

The main purpose of this page is trying to make new developers come to
ClojureScript feel better by providing informations. People in Clojure
community already knew it so I don't have to emphasis that my side is
unofficial again. Plus I added a link at the corner.

Still thanks for putting down you impressions. But I thought about you option
before when posting to Reddit.

~~~
resurge
People in the Clojure community might know that your site is not the official
one, but people new to Clojure(script) might not!

I actually thought it was the official website first time I visited the page.
(The "Back to official" link is not clear enough)

I agree with the improvements that were suggested. (different logo or putting
unofficial in the title)

~~~
jiyinyiyong
> ClojureScript(Unofficial)

Fine... Updated.

~~~
profalseidol
are you related to jinyang?

~~~
jiyinyiyong
I don't know jinyang? Who?

~~~
anaganisk
Elrc bachman would be proud

------
spinningarrow
I find the random sample snippet of code at the top of the page quite
confusing. The first time it loaded it was about threading macros and the
second time was reagent, both of which are things I wouldn’t expect a beginner
to be familiar with. Perhaps some context would be nice. Even better, how
about a snippet of code in cljs showing how people can do something they’re
familiar with in JS?

~~~
kimi
Agreed. Consider also that for someone who does not know anything about
Clojure, it looks alien enough.

~~~
jiyinyiyong
Does the first paragraph the page help? I was expecting this paragraph telling
people what ClojureScript is.

> Clojure is a dialect of the Lisp programming language. Clojure is a general-
> purpose programming language with an emphasis on functional programming.
> ClojureScript is a compiler for Clojure that targets JavaScript.

~~~
zck
Who's your target market for the front page? If it's people who don't know
what Clojurescript is, why confuse them with hundreds of characters of
incomprehensible code, with no understanding of why it's there or what it
does?

On the other hand, if it's people who are familiar with Clojurescript...also
why is it there? It's given no motivation on the page, and gets in the way of
people finding what they're looking for.

~~~
jiyinyiyong
State your backgrounds please~ ClojureScript users? Non-Clojure programmer?
Known Lisp?

Showing code is most direct way of telling people what ClojureScript is. The
official side gave thousands of words but people with less knowledge just
don't read. Code just tells, even audience don't get the whole ideas, they are
impressed.

Also the page listed quite some projects which are important to the community,
which the official one did not offer.

I made this page and collected feedbacks from ClojureVerse and WeChat group
mainly. Definitely I need to serve wider audience. Please tell me more details
what you feel confused on this page.

~~~
zck
Have used ClojureScript a little bit, Clojure a fair amount, a lot of coding
in other Lisps.

Having code is useful! Yes! But it is easier if people are guided to it. On
the reddit thread you link, you link to two tweets containing the homepages
for languages like CoffeeScript, PureScript, and LispyScript. All of these
pages have code on the main page, yes.

But note that on all of them, the code snippets are motivated. LispyScript has
eight lines of code across six heavily explained examples. PureScript has five
lines of code that come after a tagline that explains what the language is,
then ten bullet points explaining benefits. Each example of Elm code is
separately motivated. The user is never left guessing why the code is there:
the first snippet is "Javascript Interop"; the second "No Runtime Exceptions".

Compare that to clojure-script.org/. The first thing I see when I load the
page is "InterOp". Interop of what? The first English word I see on the page
is "Microsoft". Is Clojurescript a Microsoft project? This is inverted, where
the page wants to dive into details about Clojurescript before even explaining
what Clojurescript is. You wouldn't display a Western-style horse saddle,
expect them to figure out on their own the differences between that and an
English saddle when you don't state them, and you definitely wouldn't talk
about that before explaining what horseback riding is!

~~~
jiyinyiyong
Can't disagree. I didn't see the page in that way before. At first I just want
to paste some code there. If a new user came, he/she knows nothing about
Clojure and he/she does not read it. He/she gets the impression that Clojure
is a Lisp with so many garish features, nice. If a experienced Clojure user
same, he just recognized the code and thought "yes that is Clojure".

If a new user tries to read the code, there can be confusions. True. There's
still quite a gap in in front of new users who want to know ClojureScript
better. Any examples you have seen that solves the problem while we still have
so many snippets in the first screen?

~~~
zck
I think some of the other sites you linked are great examples.

So move the elevator pitch for Clojurescript to the top of the page.
"Clojurescript is a compiler for Clojure that targets Javascript" is an
explanation technically, but you might want to write something more about why
you'd use Clojurescript.

For example, the first words you see on Elm's site are "A delightful language
for reliable webapps.". So you'd use Elm to make webapps, and it should be
enjoyable to use. Ruby says "A dynamic, open source programming language with
a focus on simplicity and productivity. It has an elegant syntax that is
natural to read and easy to write." Note how none of these focus on how the
language is implemented; most users don't care. The language could have a
compiler written in Brainfuck to compile to Lua, but that's all under the
hood.

So write a sentence or two about why a programmer would choose Clojurescript
for a task. What kinds of things does Clojurescript do well?

Also, I'd suggest motivating the snippets the way Elm does, where the user
isn't left guessing why a snippet is there. It's explicitly explained.

~~~
jiyinyiyong
Hard question for me. Trying to reach for help
[https://clojureverse.org/t/how-do-you-introduce-
clojurescrip...](https://clojureverse.org/t/how-do-you-introduce-
clojurescript-to-beginners-in-one-sentence/2004)

------
geokon
I haven't found a place that explains the big picture and how everything fits
together. Is there a good resource to learn clojurescript for someone who's
never done web programming and without having to learn JS?

I'm learning Clojure now (coming from years of C++) and I love it. There is a
bit of black magic (lein/cider make cmake look like a shell script) but CJS is
a bit daunting b/c it has so many layers. CJS on Lumo on React on JS on the
DOM ... I don't actually know what any of those words mean :P

~~~
bgorman
I would highly advise newcomers to CLJS to use lein cljsbuild, reagent, and
the figwheel template. It is by far the most popular tooling for CLJS -
although recently shadow-cljs folks have been quite loud.

~~~
jiyinyiyong
I'm definitely one of shadow-cljs folks. We are trying to shorten the steps
and paths people coming from JavaScript world to ClojureScript. Figwheel is a
great tool, just not a perfect one to people with JavaScript background.

~~~
fnordsensei
Could you elaborate a little bit on how figwheel is challenging for people
with JS background and how shadow-cljs differs?

~~~
jiyinyiyong
Configuring lein scripts. Debugging JVM problems. Guess how JavaScript
developers hate JVM exceptions.

~~~
bgorman
Lein is a declarative build tool. Perhaps your problem lies with not
understanding how the tools work?

~~~
jiyinyiyong
JVM exceptions, I hated.

------
Sawamara
I could not get leiningen to install under Win10 a week ago, was quite a
sobering experience. Some site that was linked to download from got a 404,
then I got directed towards some bat script, which complained about HTTPS
certification issues (lol)?

Took less than 5 minutes under a linux server though, so thats something, I
guess. But still, its kinda mind-blowing how much Win users are ignored.

~~~
jiyinyiyong
I saw David adding commands that Windows users need in the docs. Personally I
don't like treating Windows users like how I treated Linux/macOS users. You
chose Windows, you chose the hard way, you have to figure it out on you own.

Post your question to [http://clojureverse.org/](http://clojureverse.org/) see
if others can help.

~~~
tmountain
This kind of thinking is not helpful in maximizing adoption for any
technology, period.

~~~
swannodette
Lead developer of ClojureScript here. Agreed, we take Windows support quite
seriously.

~~~
cutler
David, I think the Clojurescript Quick Start guide
([https://clojurescript.org/guides/quick-
start](https://clojurescript.org/guides/quick-start)) is a wasted opportunity.
I don't think new users want to wade through a page full of compiler flags
when Leiningen + template is the default for most of the Clojure(script)
community. This merely adds to the impression that Clojure(script) is for
experts.

~~~
swannodette
New users (and experts as well) do not find Leinginen and templates easy to
use. The response to the Quick Start has been overwhelmingly positive from new
and experienced users.

~~~
fnordsensei
I personally love the work that you've done in this area recently. I do have
the feeling that users are still exposed to quite a bit of plumbing, as they
might be used to <command> <declared intention> style commands from elsewhere
("npm install nodemon" or what-have-you).

------
holtalanm
I've been learning Clojure and ClojureScript in my spare time. I can honestly
say that one thing that would make adoption a lot more wide-spread is a better
way to include NPM modules in the project.

I know that there is a new feature for it, but the documentation was a little
cryptic. Ended up just adding some CLJSJS dependencies to my project and
giving up on using the NPM module I _really_ wanted to use.

In the end, that could be because i'm just lazy, though. I'd love to hear what
others think on this topic.

~~~
typon
Been working on a cljs project and took me a solid week to get npm integration
working. The documentation is either wrong or incomplete on both the official
site and the wikis for lein/boot.

~~~
jiyinyiyong
Still, please try shadow-cljs
[https://news.ycombinator.com/item?id=16866085](https://news.ycombinator.com/item?id=16866085)
and join us on Slack.

~~~
typon
Yep, that's what I ended up discovering and going with.

However, shadow-cljs REPL integration was also pretty hard to get working with
my editor (spacemacs), because most of the tutorials assume you're using lein
to build your project.

shadow-cljs is pretty dope though. Almost instantaneous rebuild times and
basically no setup besides a small, understandable config file.

------
doglooksgood
great job, it’s pretty hard to sell clojurescript withoit any context(I mean,
somebody tell you his success story or explain why it is good). To make who
comes here adopt on clojurescript, I think this page should have some links on
sucess story or open source applications. And it will be more attractive if it
has more logos here, instead of plan text links IMO.

~~~
jiyinyiyong
Thanks. The official sites might be the better place doing that. I'll see what
I can do on my side as well.

------
Hupriene
It's been a while since I've worked with ClojureScript. I was excited to learn
about lumo. Thanks.

~~~
jiyinyiyong
Make sure you also know the goodies in shadow-cljs
[https://news.ycombinator.com/item?id=16866085](https://news.ycombinator.com/item?id=16866085)

------
spinningarrow
On the whole, great work! Something like this is definitely needed to make
cljs more approachable.

------
philbo
Is it possible to develop CLJS without needing the JVM yet?

------
stojano
Still figuring out the keybindings for spacemacs... after mastering it, I'll
have a look at Clojure & ClojureScript. CU in 2020

~~~
stojano
Kidding... easy start documentation for it is really needed

~~~
achikin
You could try Cursive - a plug-in for Inellij Idea. Unfortunately most
tutorials suggest emacs, which is not very good for quick start.

