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