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.
)
