# Feedback wanted: draft of a Clojure REPL guide, soon to be submitted on clojure.org
**URL:** https://clojureverse.org/t/feedback-wanted-draft-of-a-clojure-repl-guide-soon-to-be-submitted-on-clojure-org/1703
**Category:** Tutorials & Guides
**Created:** [March 5, 2018, 8:30pm UTC](https://clojureverse.org/t/feedback-wanted-draft-of-a-clojure-repl-guide-soon-to-be-submitted-on-clojure-org/1703 "2018-03-05T20:30:41Z")
**Posts on this page:** 20
**Page:** 2
### Author:  [@vvvvalvalval](https://clojureverse.org/u/vvvvalvalval)
#### Post date: [March 7, 2018, 9:56am UTC](https://clojureverse.org/t/feedback-wanted-draft-of-a-clojure-repl-guide-soon-to-be-submitted-on-clojure-org/1703/21 "2018-03-07T09:56:16Z")
> [@soulflyer](#):
>
> If this kind of feedback is useful I will continue later.
Yes it is useful, totally in my blind spots. Thank you.
---
### Author:  [@vvvvalvalval](https://clojureverse.org/u/vvvvalvalval)
#### Post date: [March 7, 2018, 2:14pm UTC](https://clojureverse.org/t/feedback-wanted-draft-of-a-clojure-repl-guide-soon-to-be-submitted-on-clojure-org/1703/22 "2018-03-07T14:14:35Z")
> [@DjebbZ](#):
>
> Another idea: to explain the advantage of the REPL, try to explore and explain the difference between the usual feedback loop from other languages
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.
---
### Author:  [@vvvvalvalval](https://clojureverse.org/u/vvvvalvalval)
#### Post date: [March 8, 2018, 9:10am UTC](https://clojureverse.org/t/feedback-wanted-draft-of-a-clojure-repl-guide-soon-to-be-submitted-on-clojure-org/1703/23 "2018-03-08T09:10:57Z")
Did some major edits thanks to your feedback. [https://5aa147747b6ee8595c2301b3–clojure-site-preview-vvvvalvalval.netlify.com/guides/repl/introduction.html](https://5aa147747b6ee8595c2301b3--clojure-site-preview-vvvvalvalval.netlify.com/guides/repl/introduction.html)
1. As suggested by @ivar, I broke the guide down into chapters, each on its own page.
2. 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.
3. 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.
4. 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!
---
### Author:  [@dave.liepmann](https://clojureverse.org/u/dave.liepmann)
#### Post date: [March 8, 2018, 1:28pm UTC](https://clojureverse.org/t/feedback-wanted-draft-of-a-clojure-repl-guide-soon-to-be-submitted-on-clojure-org/1703/24 "2018-03-08T13:28:53Z")
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.
---
### Author:  [@tkjone](https://clojureverse.org/u/tkjone)
#### Post date: [March 8, 2018, 2:40pm UTC](https://clojureverse.org/t/feedback-wanted-draft-of-a-clojure-repl-guide-soon-to-be-submitted-on-clojure-org/1703/25 "2018-03-08T14:40:15Z")
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](https://reasonml.github.io/docs/en/let-binding.html) 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 🙂
---
### Author:  [@orbjet](https://clojureverse.org/u/orbjet)
#### Post date: [March 8, 2018, 7:18pm UTC](https://clojureverse.org/t/feedback-wanted-draft-of-a-clojure-repl-guide-soon-to-be-submitted-on-clojure-org/1703/26 "2018-03-08T19:18:13Z")
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 🙂
---
### Author:  [@stathissideris](https://clojureverse.org/u/stathissideris)
#### Post date: [March 8, 2018, 10:27pm UTC](https://clojureverse.org/t/feedback-wanted-draft-of-a-clojure-repl-guide-soon-to-be-submitted-on-clojure-org/1703/27 "2018-03-08T22:27:29Z")
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.
---
### Author:  [@vvvvalvalval](https://clojureverse.org/u/vvvvalvalval)
#### Post date: [March 9, 2018, 9:52am UTC](https://clojureverse.org/t/feedback-wanted-draft-of-a-clojure-repl-guide-soon-to-be-submitted-on-clojure-org/1703/28 "2018-03-09T09:52:09Z")
> [@orbjet](#):
>
> 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?
I’m not sure I understand the question, but essentially I will soon submit this guide in a Pull Request to [clojure/clojure-site](https://github.com/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](http://clojure.org).
---
### Author:  [@vvvvalvalval](https://clojureverse.org/u/vvvvalvalval)
#### Post date: [March 9, 2018, 9:52am UTC](https://clojureverse.org/t/feedback-wanted-draft-of-a-clojure-repl-guide-soon-to-be-submitted-on-clojure-org/1703/29 "2018-03-09T09:52:48Z")
> [@stathissideris](#):
>
> 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 didn’t even know about those… this confirms that this guide is needed 🙂
---
### Author:  [@vvvvalvalval](https://clojureverse.org/u/vvvvalvalval)
#### Post date: [March 11, 2018, 6:39pm UTC](https://clojureverse.org/t/feedback-wanted-draft-of-a-clojure-repl-guide-soon-to-be-submitted-on-clojure-org/1703/30 "2018-03-11T18:39:42Z")
So as promised, here’s a little ‘Rationale’ for this guide and some choices I made writing it.
> [@dave.liepmann](#):
>
> 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?
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:
1. **Lack of discoverability** of REPL-related tools and techniques.
2. **Paralysis of choice** regarding tools
3. **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](http://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.
> [@soulflyer](#):
>
> 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.
_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](https://jacobian.org/writing/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! 🙂 )
---
### Author:  [@vvvvalvalval](https://clojureverse.org/u/vvvvalvalval)
#### Post date: [March 12, 2018, 10:20am UTC](https://clojureverse.org/t/feedback-wanted-draft-of-a-clojure-repl-guide-soon-to-be-submitted-on-clojure-org/1703/31 "2018-03-12T10:20:55Z")
Submitted, waiting for review: [https://github.com/clojure/clojure-site/pull/251](https://github.com/clojure/clojure-site/pull/251)
---
### Author:  [@alexmiller](https://clojureverse.org/u/alexmiller)
#### Post date: [March 12, 2018, 2:02pm UTC](https://clojureverse.org/t/feedback-wanted-draft-of-a-clojure-repl-guide-soon-to-be-submitted-on-clojure-org/1703/32 "2018-03-12T14:02:55Z")
I’m pretty backed up this week so it may be a week or two before I get to it, FYI
---
### Author:  [@didibus](https://clojureverse.org/u/didibus)
#### Post date: [March 13, 2018, 9:40am UTC](https://clojureverse.org/t/feedback-wanted-draft-of-a-clojure-repl-guide-soon-to-be-submitted-on-clojure-org/1703/33 "2018-03-13T09:40:39Z")
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.
---
### Author:  [@vvvvalvalval](https://clojureverse.org/u/vvvvalvalval)
#### Post date: [March 13, 2018, 5:09pm UTC](https://clojureverse.org/t/feedback-wanted-draft-of-a-clojure-repl-guide-soon-to-be-submitted-on-clojure-org/1703/34 "2018-03-13T17:09:04Z")
> [@alexmiller](#):
>
> I’m pretty backed up this week so it may be a week or two before I get to it, FYI
Sure no worries, hopefully we’ve saved you some work here 🙂
---
### Author:  [@vvvvalvalval](https://clojureverse.org/u/vvvvalvalval)
#### Post date: [March 13, 2018, 5:13pm UTC](https://clojureverse.org/t/feedback-wanted-draft-of-a-clojure-repl-guide-soon-to-be-submitted-on-clojure-org/1703/35 "2018-03-13T17:13:59Z")
> [@didibus](#):
>
> I’m not sure about the advice on switching namespace to use in-ns. Its simpler to just switch namespace with ns as well
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](https://clojure.org/reference/namespaces), and tried to make the readers aware of the differences between ns and in-ns, so that they can choose for themselves.
---
### Author:  [@seancorfield](https://clojureverse.org/u/seancorfield)
#### Post date: [March 15, 2018, 6:42pm UTC](https://clojureverse.org/t/feedback-wanted-draft-of-a-clojure-repl-guide-soon-to-be-submitted-on-clojure-org/1703/36 "2018-03-15T18:42:53Z")
It’s an amazing piece of work – thank you! – and the new multi-chapter format is excellent!
---
### Author:  [@den](https://clojureverse.org/u/den)
#### Post date: [March 16, 2018, 2:36am UTC](https://clojureverse.org/t/feedback-wanted-draft-of-a-clojure-repl-guide-soon-to-be-submitted-on-clojure-org/1703/37 "2018-03-16T02:36:35Z")
Why is there no REPL in the repl guide? Klipse?
---
### Author:  [@zerg000000](https://clojureverse.org/u/zerg000000)
#### Post date: [March 16, 2018, 4:09am UTC](https://clojureverse.org/t/feedback-wanted-draft-of-a-clojure-repl-guide-soon-to-be-submitted-on-clojure-org/1703/38 "2018-03-16T04:09:08Z")
highly recommend this guide.
[https://practicalli.github.io/spacemacs/](https://practicalli.github.io/spacemacs/)
---
### Author:  [@pesterhazy](https://clojureverse.org/u/pesterhazy)
#### Post date: [March 16, 2018, 10:16am UTC](https://clojureverse.org/t/feedback-wanted-draft-of-a-clojure-repl-guide-soon-to-be-submitted-on-clojure-org/1703/39 "2018-03-16T10:16:52Z")
Wow, this is comprehensive. Maybe this should be linked from the README of Spacemacs’s Clojure layer?
---
### Author:  [@vvvvalvalval](https://clojureverse.org/u/vvvvalvalval)
#### Post date: [March 16, 2018, 6:23pm UTC](https://clojureverse.org/t/feedback-wanted-draft-of-a-clojure-repl-guide-soon-to-be-submitted-on-clojure-org/1703/40 "2018-03-16T18:23:09Z")
> [@den](#):
>
> Why is there no REPL in the repl guide? Klipse?
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](http://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.
[Previous page](https://clojureverse.org/t/feedback-wanted-draft-of-a-clojure-repl-guide-soon-to-be-submitted-on-clojure-org/1703.md?page=1)
[Next page](https://clojureverse.org/t/feedback-wanted-draft-of-a-clojure-repl-guide-soon-to-be-submitted-on-clojure-org/1703.md?page=3)