Oh yeah! I think I got it from you if I remember right. What did you think of that episode?

Of course I hoped he would have liked it, but 2 weeks might be too short to get past the superficiality of the syntax

I'm one of those people who loved the Lisp syntax from day 1, but there's a lot of people who it will have to grow on over time, and some people will just never like it

Same. It also sounds like he didn't even use the REPL at all.

if you listen to the episode after it or the one after that, you'll note he might try it again

He did mention it in the episode too. He seemed to be receptive to his merits, just doesn't enjoy lisp. It's kinda funny since the reason he disliked it was the reason I liked it: Not having to think about syntax almost at all. However, he also didn't make use of any LISP editors such as paredit or parinfer.

This got me thinking would it be worth creating a git-book that serves as a modular getting started guide that covers most the popular tooling choices and some of the philosophies of working with Clojure?

Admittedly Clojure did lose me my first go of it. I found learning BOTH the syntax and FP concepts a bit overwhelming. However, after studying FP concepts in my day-to-day JS for a year, my second attempt really clicked.

But if there was one git book for beginners that cover VS Code, Atom, Spacemacs, and VIM with helpful guides and pointing to the many more detailed resources out there: Would it ease the pain for people coming to Clojure having a stronger background in imperative, c-style syntax trying to use the tooling their comfortable with?

My general recommendation to anyone learning Clojure is to stick with the editor you already know if possible, to at least avoid two learning curves at the same time!

That makes sense. I suspect most would agree with that. Unfortunately, the host did not understand why working with the REPL was important or what the LISP tooling offers which I think soured their first taste. Treating this as a UX test, I feel it unveils a strong starting place for improving getting started documentation.

I quickly brainstormed the structure of such a guide. Any thoughts? https://www.dropbox.com/s/wzyi7m3nnfzthap/getting-started-clojure.pdf?dl=0

I wouldn't bother with Boot at all in such an introductory guide, and I'd choose a different name than "inferior" for the non-nREPL flavor because everyone except Emacs weenies is going to get the wrong idea.

How would you describe that behavior? Sub-process REPL vs nREPL?

I think it needs to be pretty minimal overall with the goal of getting people up and running a.s.a.p. with a "correct" workflow.

Well, for Atom/Chlorine, it's actually a Socket REPL, not even a plain/standard/basic REPL.

I think the whole distinction is distracting, when you get started.

That's a good point

I would have a very short intro section that emphasizes the real basics of Clojure and that RDD is important, then a section for each editor that readers might already be using: IntelliJ -> Cursive, VS Code -> Calva, Atom -> Chlorine (ProtoREPL is pretty much abandoned at this point), Emacs -> CIDER, Spacemacs -> CIDER (presumably).

With absolutely the bare minimum to get up and running and get "productive". And I'd stick to the standard CLI/`deps.edn` if possible since the docs for that are official (and the Powershell install for Windows is pretty solid at this point, even for a pre-alpha).

That said, some of the editor options are going to rely on nREPL and that's easier to start up with Leiningen -- but I'd only go that route if the editor/integration does not work with CLI/`deps.edn` easily.

I think we're on the same page about the short intro\part 1.

Your mindmap suggests a longer intro than I would suggest 🙂

For nREPL with CLI/`deps.edn`: https://nrepl.org/nrepl/0.6.0/usage/server.html

Even easier:

clj -Sdeps '{:deps {nrepl {:mvn/version "0.6.0"}}}' -m nrepl.cmdline -i

(but, yeah, it makes sense to add it as an alias in deps.edn)

Haha ok, I'll trim it then 🙂

What would you consider basic\important enough to put in that brief intro?

For Atom/Chlorine, you'll want something like

:chlorine {:extra-deps {compliment {:mvn/version "0.3.9"}} :jvm-opts ["-Dclojure.server.repl={:port,5555,:accept,clojure.core.server/repl}"]}

Intro: REPL - brief explanation, key to productive Clojure; Parentheses - Clojure-aware editors make this a non-issue "No, really!"; FP/Language - just link to relevant http://clojure.org pages. No need to duplicate anything from http://clojure.org really.

REPL section could link to (extensive) REPL guide on http://clojure.org at the end.

Skip build tools. Not relevant to starting to use Clojure. Point to getting started on http://clojure.org for installing CLI/`deps.edn` stuff at most.

Agreed.

Then pick an editor.

For each editor, show the deps.edn alias, show the command-line to start an interactive REPL, explain the minimum packages needed in the editor, explain how to connect to the existing REPL, explain eval form / eval top-level form / and how to view doc / source for each editor.

Real bare bones stuff.

Do you think it would be valuable to at least introduce deps.edn\clj and how to install it in a section between the intro and editor configs?

That is on http://clojure.org -- just tell folks to read (& do) that one page.

Assuming this isn't their first clojure resource, they may have seen a few tutorials, guides, etc.. for many different tooling setups. No need to explain them all.

Depends on your audience -- if you want this to be "Try Clojure (the right way)" or "The Right Way (to do Clojure)"? 🙂

But seriously, pick one (I think you started by going after the first one?) and streamline everything to match that.

Fair point. Perhaps add an optional FAQ section below.

@U04V70XH6 How's this version https://www.dropbox.com/s/pxb9rhpdogbkaaw/getting-started-in-clojure-0.2.pdf?dl=0?

I'm not going to agree that lein/`boot` are geared to bigger projects -- given that we happily manage a 90K line monorepo with clj 🙂

Good call on adding vim!

Atom: rainbow parens has performance issues -- avoid. Minimal setup is chlorine, parinfer I think. lisp-paredit is a "nice to have". Check with @U0ETXRFEW about minimal Calva setup.

Yeah, overall, looks good!

I would say of lein/`boot` that they are older and therefore they (esp. lein) are more common in books/tutorials at the moment. I would also categorize them as "easy" rather than "simple" -- and indicate that CLI/`deps.edn` is "simple" and is designed (by Cognitect) to follow Clojure's principles.

Ok thanks for the feedback! Going to copy it into my notes and bust out another iteration in a couple of hours.

About Calva setup. Calva includes Paredit, and also bundles rainbow parens. There is no need for a deps.edn alias. When you connect Calva to the project it starts it for you, injecting its dependencies.

Right, but I think it would be good for the guide to be consistent and have each editor integration described in terms of starting a REPL from the command line and then connecting the editor to it -- because that's a "common denominator".

Why is the common denominator important? Each reader is supposed to pick up the section of his particular choice of editor, right? To me it makes sense to write each such section tailored towards the Tao of the tool.

I believe the suggestion is that if you have some common denominator among all of the editor environments, like the clj/`clojure` CLI and deps.edn being used for the project, then you can have N versions (N=# of editor environments) vs. N*M (M=# of non-editor build/deps environments, e.g. leiningen, boot, maven, deps.edn)

Who would want to write N*M versions of this?

@jayzawrotny one piece of feedback: for editor integration I really recommend setting up a linter ;-)

My instinct here would be to start with Pez’s option as a quick connect then at the bottom cover deps.edn alias — which may be a good practice for projects that are intended for collaboration with devs that may not be using Calva? If it means anything the host of that podcast did start with deps.edn as well.

@U04V15CAJ Hmm if readers are just starting with Clojure wouldn’t they have enough errors barking at them?

I’m not against that idea though. 😀

Since they might have trouble working with the REPL at first, static linters like joker and clj-kondo are really helpful imho, e.g when making typos or wrong number of args

Or even just basic syntax

I’ll add it to the doc. Would anyone else like to weigh in on if linters are helpful while learning the language?

Sounds good with the quick-connect first, @jayzawrotny. Calva does ask about which aliases to launch with, so if the instructions are ”Leave all aliases unticked, for now”, it could be added that there is reading about aliases below.

About linters, they can save your sanity beginning with Clojure, I think. Figuring out what is stopping your code to work can be a really tricky. (To this end I am aiming to get linting down to an opt-out setting in Calva, where the user does not need to install anything else but Calva, and linting is just there.)

@jayzawrotny I think the linters I mentioned give you a lot of the static benefits that Cursive give you, without using IntelliJ. Obviously I’m biased.

Gives. Phone. Spelling...

Those are great points. I think trying to set it up myself will guide my slant on that more. If it’s easy to setup I’ll include it for each editor, if I struggle or the setup process is too involved I may choose to reprioritize it on an editor-by-editor basis.

For VS Code I think it is not easy enough yet. It gets messy with all the OS specific stuff in such instructions. Maybe just recommend the user to consider adding a linter to the setup, providing a link to instructions. I can write a Calva wiki page you can link to. I should write that page anyway.

That sounds good to me.

https://www.dropbox.com/s/tiifl0ezhjdjgtk/getting-started-in-clojure-0.3.pdf?dl=0

The Calva quick connect doesn't need this split: * start an interactive repl * connect to existing REPL It is rather something like: * Let Calva launch the project and connect the REPL.

I have never used Calva -- does it auto-detect boot/Leiningen/deps.edn and use whatever, or is it limited to a subset of those?

Leiningen, deps.edn and shadow-cljs, so far. Boot yet to be added.

Boot is a bit more difficult since it’s not a predictable config file format I guess?

And also lein-figwheel, Figwheel Main and shadow-cljs. Amd project custom cljs repls can be configured. (We are working with improving that last part a few notches right now.)

Yeah, I don't know how to deal with Boot, tbh.

What I usually do is start an external REPL with boot and then cider-connect

I’m also doing that with lein and tools.deps

Jack-in is a bit too magic for me

Yes, Calva lets you connect to projects with nREPL. This is a jack-in limitation.

https://www.dropbox.com/s/ks5tsvghpxzs3w4/getting-started-in-clojure-0.4.pdf?dl=0 it’s getting late. Later all 😴

in clojure-nl there was a guy who did an intro for true beginners with clojure and I think he used: https://sekao.net/nightcode/

so for trying it out it might be nice as well, I dunno. It takes away the vast majority of the mental overhead apparently.

It sure does. I think you can include Nightcode in the project? Might be nice for people who just want to check Clojure out. No need to install anything for the RDD.

About lein and boot being ”Other build tools somewhat similar to clj/deps.edn but more geared towards bigger projects”. deps.edn is not a build tool, right? I think I have read someone at Cognitect stressing that point even.

I was thinking about that one too. It deserves mentioning but I think it should go into the FAQs... I had another idea for a project that it might be better suited for. Imagine a survey you fill out that pairs you with your ideal Clojure learning experience. If you don’t like books, don’t want to configure editors, then Nightcode is perfect!

That sounds like a cool project idea, maybe I could annoy the meetup guys into working on it.

@UGFL22X0Q Maybe this will help people get started? https://docs.google.com/spreadsheets/d/1wXP7FwdQsaZlK6ZdpcL-XzRoVKifrXiXky-c0xEByD0

maybe! Gotta sell them on the idea first though.

Maria definitely has a place in this, it's tailor-designed for beginners and you don't have to install anything to jump in and get started

oops, just realised it's already in the above spreadsheet

The reason I suggested the "start REPL, connect editor to REPL" approach for all editors is that it is "baby steps". Nearly all Clojure intros start with a bare REPL and expect beginners to type into it. So the only difference here is to start the REPL in such a way that they can connect an editor to it and then see how they can switch from typing-into-REPL (per most tutorials they'll encounter, and the http://clojure.org guides!) to evaling-from-editor without having to deal with a whole new way of getting an editor started inside the editor.

@U0ETXRFEW Re: Nightcode -- the whole point of this guide is to encourage folks to try out Clojure in the editor they already use -- which is why VS Code was one of the first listed.

Yeah, maybe Nightcode doesn't fit neatly into this guide. To me Nightcode just seems like such an excellent approach to the task of removing barriers to entry.

Regarding the REPL prompt. I think it makes sense to introduce it with the simplest command line possible, clj, no aliases, no nothing. Then continue with that another way of getting to a REPL prompt is to open a Clojure project in your favorite editor, and jack in. Then introduce that the same editor gives you access to the REPL inside the files themselves. (Maybe even mention that some people only use the prompt occasionally, staying inside the files for most explorations. But that might be occurring to me because it happens to be my personal preference for using the REPL)

@U0ETXRFEW I know this is a (very) long thread but I wanted to check you've read all the initial discussion around this?

This all came about because of a blog post by a guy who tried Clojure but dismissed it because he didn't get up and running with his existing editor enhanced with some bare minimum necessary add-ons and a good RDD workflow. So the point of this guide is to provide a very simple, straightforward path to a good RDD workflow with whatever your current editor is.

It's not meant to be a full guide to any specific editor.

Each editor-specific section should be simple, offering a single, basic approach for folks completely new to Clojure to get that editor -- that we assume they already use -- up to speed in the minimum number of steps.

Each section can then point off to deeper documentation about the editor, Clojure integration, and stuff like integration with lein/`boot`/jacking-in and so on.

But the baseline is: get CLI/`deps.edn` installed. Learn how to start a REPL (with clj) that you can type into and that your existing editor can connect to. That's it. The quickest, simplest path to RDD.

The guide should not overwhelm users with options -- they can deep dive later into any particular editor. The guide benefits from having all editor sections follow roughly the same path so that readers can see that they're not locked into any particular editor based on the choices they make about how to start REPLs etc: the same simple approach works for all editors.

The only real difference is whether to start nREPL from the command line or also start a socket REPL (for Chlorine).

I've read the thread. And I have also started to listen to the podcast episode to gain more context. Will finish listening to that tonight. I think I am pointing at a very straight path to getting started, and I am totally aware that it is not about a specific editor. Also agree about not overwhelming with options.

https://www.youtube.com/watch?v=9wUg6enmOeM

Right, so now I have listened to the full episode. Very good stuff, all of it. Because they used Calva I learnt tons from listening to it. And I do wish I could do more about the Parinfer situation (that was a painful part to listen to). Anyway my takeaways are that I am glad I had colleagues introducing me to Clojure, that people need to quickly find the structural editing help, and that the Clojure coding workflow needs to be highlighted much more. I think the guide being developed here will do wonders, and I will think really hard about how Calva can be adapted to help in these first steps.

@U04V70XH6 but what If you've never used any editor before (as in absolute beginner?) The closest way to "not learn an IDE at the same time as learning the language" would be an app that has all that stuff all included.

but if that's not the scope of the idea, I guess it's fine.

@UGFL22X0Q complete beginners need a different guide, I agree. This guide is for programmers who want to try clojure -- to get them into an RDD workflow with their existing editor because that's the past that is so very different with clojure.

I think night code is a good place for complete beginners to start

Yeah, totally agree then, wasn't sure of the demographic.