Fork me on GitHub
#improve-getting-started
<
2022-03-20
>
pavlosmelissinos10:03:46

Personal opinion follows: I'm pretty sure that the modular/unopinionated approach of Clojure has prevented people from picking it up. Seasoned engineers like being able to tailor development tools to their existing workflows but beginners require an out of the box experience that works well and Clojure doesn't have one yet. The official https://clojure.org/guides/getting_started does have all of the necessary information but it's still quite chaotic for a beginner. It links to https://clojure.org/community/tools but it doesn't offer any direction beyond that. It's like "here's what's possible, now you're on your own". It has to become more opinionated than that, getting started guides don't need so much choice nor information.

👆 1
pavlosmelissinos10:03:59

> Clojure requires Java. Clojure officially supports Java LTS releases (currently Java 8, 11, and 17), but also tries to ensure interim versions work as well. You can use any Java installation, whether it’s a commercial release from Oracle or an open source version based on OpenJDK (like Temurin). > The Clojure tools require that either the java command is on the path or that the JAVA_HOME environment variable is set. Why is this relevant information in a getting started guide? Why not just say "Download OpenJDK17 (link)" and have a tooltip with the rest of the information? People who know/care what Temurin is will know which version of java they have installed and will be able to adapt. Beginners don't have that luxury.

pavlosmelissinos11:03:37

I've been thinking that it would be awesome to have a step-by-step guide in the official site (or at least endorsed by it) that would help newcomers create a non-trivial program from scratch. It would be a great way to show how the different tools (tools.deps/tools.cli/etc) connect to each other and demonstrate how gracefully Clojure programs are built, iteration after iteration.

pez11:03:58

Beginners come in many shapes, though. You could be a seasoned Java dev, beginner in Clojure. An instruction to install a particular JDK might raise questions/worries ”does this mean I can't use Temurin?”. I think you are raising good concerns, and probably a shorter, less open ended, getting started. Just noting that the trade-off is there. Tooltips provide some wiggle room, as you are suggesting. I've found that using <detail> with questions (e.g. ”Can I use other Java versions?”) to be effective. My Ux testing on the Calva guides indicate that if people see their questions under a heading they can expand, they relax from the mere fact that the question is addressed, even if they don't always have the actual need for the answer, right there and then.

5
Alex Miller (Clojure team)12:03:13

The Java info is there because people often ask that question

Alex Miller (Clojure team)12:03:05

But I agree the getting started needs a lot of work. There is a branch where I've redone a lot of it but it kind of stalled out on the specific tool stuff in particular. Planning to get back to this soon.

🙏 3
metal 2
pavlosmelissinos14:03:40

> You could be a seasoned Java dev, beginner in Clojure Right, I didn't mean to insinuate that everyone has the same background but that's definitely a valid point, thanks for making it clear! > The Java info is there because people often ask that question I understand that there's a reason everything is the way it is right now and I'm really grateful for all the effort that has been put. I didn't mean to shun any of the good work that the core team and the community has tirelessly been doing. However, I'm trying to illustrate that the getting started guide (any getting started guide really): 1. has to evolve in order to suit the needs of the community over time, hence the need for a partial rewrite every once in a while. I think this has to happen regardless of how good it was when it was originally written/last edited, 2. can't contain all the information for every possible use case out there, hence the need for opinionated suggestions. Incorporating frequently asked questions in a way that won't break the flow for people who don't even know if this additional information is relevant to them would definitely be awesome. Expandable sections a la https://calva.io/get-started-with-clojure/ or putting some of the text in a separate FAQ section could potentially improve the UX.

Eric20:03:03

I agree with @UEQPKG7HQ that having an opinionated, straightforward way for beginners to get going is important. For addressing: > Beginners come in many shapes I have an idea. Maybe it's a bad idea or would be difficult to implement.

Eric20:03:48

What if the Getting Started material was organized by section like a Choose Your Own Adventure novel?

metal 1
Eric20:03:05

The end of each section could have 2-3 statements that are links to different content. • I'm following, but please continue on with the basics. 🙂 • That topic is really interesting and I'd like to go down the rabbit hole a bit to see what my options are. :thinking_face: • I'm an expert and this is boring me. Let's skip ahead to topic X. :face_with_monocle:

1
Eric20:03:10

Something like that.