Feedback wanted: draft of a Clojure REPL guide, soon to be submitted on clojure.org


#1

Hello all, I’ve been working for the last weeks on a REPL Guide, that I will soon submit as a contribution to clojure.org. Here’s a preview of the draft, please tell me what you think!

When giving feedback, it helps if you can describe your level of experience in Clojure, as well as your expectations for such a guide.


#2

This is very impressive work.
The only suggestion I have would be to break down the sections into their own pages. There is too much to manage on one page, and being able to navigate to a subsection would make things more manageable.
(Though perhaps clojure.org has a styleguide that your work already adheres to, in which case feel free to ignore my suggestion :slight_smile: )


#3

I don’t use Clojure REPL much. I feel this guide is too long. I don’t want to know every detail in Clojure REPL, but I want to know most of the tips that I would need in my real work. Tips like Boot can be external links. Installing Boot is not easy task also, why do I want to try Boot when I’m learning Clojure REPL.


#4
  1. In “Investigating Exceptions”, the last paragraph says

visualizing the Exception makes it easy to diagnose

Then you print the Exception and leave the reader alone. The guide should explain clearly where the interesting information in the Exception is, how to find it and how to fix the code.

  1. Below, you talk about Javadoc but the example shows a function that returns true, whereas the following examples (inspect-table and browse-url) explain what the code will do.

  2. The guide is super long. I’ve stopped at the Annexe at the end. Now I like that the guide is written for total beginners in Closure, I even learned a few things. Not sure how it fits with the rest of the existing guides.


#5

Yeah… it’s long, and I don’t really want to cut things from it, because I think discoverability is more important than succinctness in this case: my main goal here is that readers of all levels can achieve in a few days a mastery and understanding of the REPL that has taken me years to build up.

I think I’ll break it down into chapters as is done with the Learn Guide, but that would require me to do some fiddling with theme files that are not under version control - so please try to bear with the long page for now, the time for us to get the content right.


#6

I’m not sure what to make of that, can you clarify what you mean? To me it could mean any one of:

1.“I don’t think the REPL is useful” (and therefore neither is this guide)
2. “I’d like to know why the REPL is useful”: there’s a paragraph about that in the introduction, can I improve it?
3. “I’m don’t have much experience with the REPL”, in which case thank you for the clarification.

About everything that you see in this guide, I use in my everyday work. Some of it you may not need, but if I leave it out, it will take much more effort for people to discover it on their own than to skim through a boring paragraph :slight_smile:

  1. The CLI tools are not available everywhere (e.g windows)
  2. People may join or have existing projects using Boot
  3. I’m being consistent with the getting started guide.

#7

@DjebbZ All fair points, thanks, will incorporate them


#8

Yeah, I’m not sure of that either, which is all the more reasons to make it beginner-friendly IMO. People coming to it may have all sorts of previous experience, so I’d rather assume little about what they already know.


#9

I have three main points: length, the beginning, and your goal.

First let me say that you obviously worked very hard on this, and it shows. It succeeds in being quite comprehensive. I’m critical only because this article is so important to get right and because you are clearly productive enough to handle these changes.

One: Length

Consider the old writer’s advice, “kill your darlings.”

My main critique is also that it’s too long. As fans and experts of a topic, it’s natural for us to think “let’s teach the beginner everything!” and therefore write an exhaustive introduction. Most times that confuses the reader’s goals (utility) with our goals (completeness). For instance, just the single topic of turning the existing REPL subpage into a beginner-friendly walk-through would itself be an entirely valid full-length article. That leaves room, of course, for other full-length articles that would cover other aspects of using the REPL.

Instead, this guide seems targeted at describing all the ways to use a bare REPL, assuming the reader starts with close to zero knowledge. This is a difficult space to occupy, because being comprehensive and being a useful walk-through for beginners are fundamentally two different goals. A good example of this is the Navigating Namespaces section. Phrases like “Here are 3 ways to make sure myproject.person-names is loaded” should be a flag that a beginner walk-through is getting exhaustive—in the sense of “exhausting”.

This feels like a circumstance where the very natural instinct to teach everything is the wrong approach. Most people don’t want to or even can’t learn everything in one giant lesson.

Two: The Beginning

On to specific feedback. The beginning of any article is most important, so I’ll focus there.

Why use a Clojure REPL? Clojure programmers use the REPL a lot.[1]

That doesn’t answer the question. It’s also a bad sign when one of the first sentences in the article already sends the reader to a footnote. And there’s another footnote in the next sentence! This tells the reader the article will be heavy and difficult to work through. Does the information in these footnotes—that Clojurists use the REPL more than Pythonists, because it’s better in unspecified ways—really warrant this cost? I argue not. A rewrite that decides what is important to say and then says it all without footnotes would greatly improve these critical first paragraphs.

Using the REPL can yield a very productive programming experience, thanks to the tight feedback loop it provides.

Because it’s the entire reason for the article, this sentence needs to be more persuasive. It needs to really sell the REPL. Rewriting it until it is concise and descriptive should be a high priority because this sentence is responsible for getting people to read further or not.

You say the Enhancing Your REPL Workflow section is a “must” for working with Clojure at a professional level. Is it? In it you point the user to a list of editors, the Gorilla REPL, unravel, rebel-readline, Nightcode, three different dataviz libs, the socket server, tools.nrepl, and unrepl. The impression is that the user should be in fact be using all of these, or at least trying and evaluating each of these, in order to do professional Clojure work, which is not the case. What’s the goal of this section? Is there a way to reach that goal in less space?

As soon as you start developing non-trivial programs (such as a hobby web app), you will the notions of at least the next 2 sections: Data visualization at the REPL and Navigating namespaces.

  • Missing word at “you will _____”.
  • Do you mean to describe a hobby web app as trivial or as non-trivial? This is ambiguously phrased.
  • If you’re already telling the reader they might not to read 2/3 of the article, then you have already admitted that this needs to be split into multiple articles.

Three: Your Goal

Finally: what’s your goal for the reader? What do you expect the story arc of the reader to be—they come to the article with X, and they leave with X plus what?

The reason I ask is that I expected it to be a guide about using the REPL, yet there’s a strong sense that the reader is being deceived about actual REPL usage. The majority of experienced Clojure developers use editor integration because we want to work with our source files and because we know that copy/pasting from an editor into a command-line REPL is annoying and time-consuming. So why force a beginner into a workflow that we ourselves don’t accept? It undermines the whole project of selling lisp.


#10

Thank you for this detailed review @dave.liepmann ; it challenges the current draft on important aspects, and I will elaborate on them soon in a more detailed answer.

In the meantime, if that’s not too much to ask, it would help me a lot if you could suggest concrete alternatives where my style and phrasing fall short (especially in the introduction as you mentioned). Keep in mind that I am not a native English speaker, let alone a writer :slight_smile:


#11

You wrote this, therefore it’s too late—you’re a writer! :smiley:

I mentioned all the specific instances where the phrasing needs improvement. Those spots, like “Using the REPL can yield…”, all seemed like places where it just needs a few iterations to figure out what you in fact want to say. I detected no non-native-English trouble.


#12

Me: Keen amateur, several years of non-professional clojure use, strong computing background, obsessive compulsive perfectionist.

This is brilliant. If this was around when I started playing with clojure a few years ago I could have saved countless hours of finding things out the hard way. It’s still useful now, there were one or 2 a-ha moments. I read through it fairly quickly but If you want I will put my English teacher hat on and do a more thorough check of the grammar for you. Initial impression is it probably doesn’t need it though.

Good stuff…


#13

This kind of feedback is welcome as well. Grammar should be okay, wording and phrasing less so. Luckily for you, you won’t have to hear my accent.


#14

Great work! It’s such a long article - were you wanting folks to push PRs to you, somewhere, for updates? Or just drop long revisions into this thread?


#15

This thread will do, not need to get Git involved :slight_smile:


#16

I’d love to hear you expand on this. The REPL is absolutely core to my entire workflow in Clojure. I always have at least one REPL open. I use it to evaluate code as I write it. I use it to run the application I am developing. I use it to develop and run tests. I use it to explore new libraries (both Java and Clojure). I find it hard to imagine what a Clojure development workflow looks like that “doesn’t use the REPL much”.


#17

It’s a hard question. Indeed editor integration is the best, but how to introduce it without getting into the specifics of editor X ? Genuine question, I don’t have an answer. Food for thought.

@vvvvalvalval I hope you’re keeping your article under version control, because this content definitely has a place somewhere on the internets.

Otherwise i think the feedback of @dave.liepmannis is very valuable. Completeness is often what experts want to convey, whereas if the article is meant to be a “Getting started with the REPL” guide it just needs to go to the essential.

Some random ideas (more food for thought):

  • don’t waste to much time on interacting with just the REPL, most other languages do have a similar tool (Node.js, Ruby, Haskell etc.)
  • since the true power is when you interact with a running program, maybe put the focus here
  • my previous statement may be completely wrong since Rich said several times that you can use the REPL to build programs incrementally. Show this too
  • again editor integration combined with a running program, since it’s the killer feature of the REPL.
  • since it’s all about interactive programming, screencasts are definitely a good way of showing it. You did a good job already, maybe the article needs more of them ? I think a good screencast for the section where you explain the advantage of the REPL (in addition to rephrasing as Dave suggested) could show it clearly, then the rest of the article could just be a guide to incrementally arrive at the same result

Keep up the good work, you’re doing a very good service to the Clojure community.


#18

Another idea: to explain the advantage of the REPL, try to explore and explain the difference between the usual feedback loop from other languages (write-compile-run, or write-refresh-run in the web browser) and the much faster REPL feedback loop. Try to convey the idea of the REPL as a better pen and paper thinking tool, or whatever image and approach you find.


#19

Short anwser: I write ClojureScript. Checkout http://memkits.org/ and http://mvc-works.org/ .

It doesn’t mean I don’t need to run code snippets in runtime, but in running ClojureScript, actually JavaScript, I got a REPL in Console. Meanwhile shadow-cljs watches files and hot replaces on file changes so I don’t need (require 'x :reload) either.


#20

In the intro:

, you will the notions of at least the next 2 sections: Data visualization at the REPL and Navigating namespaces.

How about “you will need the [ideas presented in] the next 2 sections” or “you will find the next 2 sections useful” Whatever you choose, I don’t think it should be “notions”, it’s not normally used in this type of context.

In a couple of place you use something like this:

You should see an output like the following:

I think of output as uncountable so would prefer there wasn’t an article. However that could just be because I’m English. I suspect this is perfectly acceptable stateside.

In Calling Clojure libs from the REPL you say

…to make that lib’s code loaded and available in the REPL.

Maybe "load that lib’s code and make it available in the REPL"
A few lines below that:

also lets use define an alias

I think that should be “lets us define…”

A bit further down you say:

We recognize the doc, source and dir operations we’ve used so far.

If you don’t exactly remember the name of some Var, you can search for it using apropos:

At first I didn’t know why you had added that first line. I guess it was to introduce appopros, so maybe “Doc, source and dir operations are easy to remember but if you don’t exactly remember…” or something like that.

If this kind of feedback is useful I will continue later. I stopped at Investigating Exceptions