Yes it is useful, totally in my blind spots. Thank you.
It’s tempting, but a bit delicate. I’m a bit wary of this approach (explaining stuff relatively to a mainstream technology), because it can be needlessly beginner-hostile. We already have too much material in the Clojure community that assumes familiarity with a mainstream language. I’ll see if I can articulate it well.
1 Like
Did some major edits thanks to your feedback. https://5aa147747b6ee8595c2301b3–clojure-site-preview-vvvvalvalval.netlify.com/guides/repl/introduction.html
- As suggested by @ivar, I broke the guide down into chapters, each on its own page.
- As suggested by @dave.liepmann, I did a full rework of the introduction. Still a bit too abstract for my taste, but hopefully it’s better.
- In reaction to @dave.liepmann’s criticism, I emphasized in various places the fact that the guide is not meant to be read in one giant session: readers should only go as far as they need, either by adding admonitions or by adding structure to the guide.
- I also incorporated various improvements from the suggestions of @DjebbZ @soulflyer.
@dave.liepmann answer has also led me to formalize a rationale for the guide - posting it here soon!
2 Likes
The intro is much better.
I recommend dropping the word “very” from “very interactive development experience”.
Breaking it into sub-articles is a big improvement.
1 Like
Hey there! Great stuff. The only suggestion I can think of, and it is more general, is perhaps making comparisons to other languages? For example, if you take a look at docs for the reasonml let binding you will notice that they compare it to what this would be equivalent of in another language. I have found that docs like this make the reader, no matter the background they come from, more comfortable. Its like tapping into something they already know and thus makes them more comfortable with a concept that, at first, can seem foreign.
Hope this helps 
2 Likes
Really nice and clean guide. I wouldn’t touch anything else.
How will the guide follow newer versions? If it starts to get obsolete what is the “update” consent?
I guess bottom links of the first page should be updated to new pages?
Anyway great effort nonetheless
Wow, this is very impressive work!
It’s quite long as it is (which is a good thing) but maybe it’s worth having a section about printing long data structures? For example, *print-length* is very useful when you have loads of data that you don’t want to print by mistake. Similarly *print-level*, and all the other *print- vars.
I would also mention that CIDER (and possibly some other REPLs) have “pretty” modes where they pretty-print by default.
I’m not sure I understand the question, but essentially I will soon submit this guide in a Pull Request to clojure/clojure-site. I guess Alex Miller will review it and merge it if all goes well. After that, anyone can submit changes to the guide via other Pull Requests, as for the rest of clojure.org.
1 Like
I didn’t even know about those… this confirms that this guide is needed 
So as promised, here’s a little ‘Rationale’ for this guide and some choices I made writing it.
This guide is for Clojure programmers who, at some point in their Clojure journey, want to become more proficient at using the REPL. This can include hobby Clojure beginners, professional programmers joining a Clojure team, and even experience Clojure programmers. The guide should make little assumptions regarding the experience level of the reader: in particular, this guide is not especially for beginners, but it must be inclusive of beginners.
I think the major pain points of the community which this guide should address are:
- Lack of discoverability of REPL-related tools and techniques.
- Paralysis of choice regarding tools
- Tooling friction
1 implies that this guide must provide access to the wide variety of REPL tools and techniques out there: it is critical that this job is done by clojure.org, because the official site is by far the main portal to the Clojure ecosystem. This can’t really be solved by another blog post or book, because the material would just float out there on the Web.
2 and 3 imply that we can’t be happy with just providing a list a libraries and articles - we need to motivate the problem them solve, give the reader the necessary background do understand how they work, and accompany the user through using them if necessary.
This. This is what I’m after! So far it has taken months or years to Clojure programmers to slowly grow their mastery of the REPL, and there are probably many more who just gave up.
In particular, I don’t think this guide should especially strive to sell Clojure via its REPL experience, because this not where most outsiders will be looking for this. However, I do think this guide can help in selling the REPL experience indirectly, by turning Clojure users into evangelists with a great development experience at the REPL, and accessible words for describing its value proposition.
In the terminology of Writing Great Documentation: What to Write, this is a topical guide, and as such its primary goal is comprehensiveness. It’s not a tutorial introduction to the REPL, because any Clojure tutorial introduction already does this job; neither is it reference material, as it wouldn’t really help with the lack of discoverability and paralysis of choice problems mentioned above.
Therefore, regarding length: I don’t think the appropriate solution is to cut down sections, rather to add the appropriate structure, guide the reader to the sections relevant to her, and make each section no more verbose than it needs to. Hopefully I’ve done that in the second posted draft, by breaking the guide into chapters. As an analogy, consider than no one ever complains about a travel guide being too lengthy, because they never expect to read it in full in the first place (which is unfortunately not the case for reviewers: thank you for your patience! )
3 Likes
I’m pretty backed up this week so it may be a week or two before I get to it, FYI
I’m not sure about the advice on switching namespace to use in-ns. Its simpler to just switch namespace with ns as well
All previous require will still exist, and you can require more things. Personally I find it easiest to just use ns all the time, to create as well as switch namespace.
Sure no worries, hopefully we’ve saved you some work here
I’ve considered both approaches, and both have their benefits and pitfalls. For instance, if you accidentally use ns to switch to a lib’s namespace without having loaded the lib first, you will have ruined your ability to load the lib easily. I have simply chosen to stay consistent with the reference on namespaces, and tried to make the readers aware of the differences between ns and in-ns, so that they can choose for themselves.
It’s an amazing piece of work – thank you! – and the new multi-chapter format is excellent!
1 Like
Why is there no REPL in the repl guide? Klipse?
Wow, this is comprehensive. Maybe this should be linked from the README of Spacemacs’s Clojure layer?
Klipse is not a full-featured REPL, only interactive snippets; as such, it may be useful in a lot of places such as language guides, but would be misleading in a REPL-focused guide.
What’s more, since this is clojure.org, we want to describe JVM Clojure, so in-browser ClojureScript REPL are not a good fit. I think gifs + code snippets will do a fine job.