Improve/add next steps for beginners

[dmitriid]

What is this about?

This came from a discussion over at Hacker News. Tl;dr is this: after looking at code examples and working through the guide on REPL, there's no next step:

• how do I set up a project/project structure?
• how do I build a project (do I somehow compile a jar? and executable? does clojure produce executables?)
• how do I run something I built?
• how do I deploy things?
• how do I set up, write, and run tests?
• how do I configure an application/build (dev vs. test. vs prod. etc.)?

There are probably a few more that I can't recall right now, and I haven't tried to start with Clojure in a while. But the above would be my immediate and next-to-immediate questions. And I clearly remember how frustrated I was that I had to google everything because the docs couldn't provide me with answers.

What does documentation have now?

Getting Started somewhat off-handedly mentions that there are CLI tools and some build tools. These mentions are not really prominent and it's not immediately apparent that you need to go there for some further info.

Learn Clojure jumps into code examples that shows evaluation results for various code snippets. And it doesn't mention REPL until later in the page, and doesn't show how to run a REPL to try these code examples until chapter two of a separate REPL guide.

Deps and CLI Guide is mostly about dealing with libraries and dependencies. It has a very short mention on how to write code in a (single) file and a short mention on how to include test directories.

From there on a beginner will be forced to only rely on Google and the kindness of strangers :)

What the documentation most likely needs

It needs at least one more chapter probably called "What to do next" :)

It should have short sections that go something like this:

• How to setup and build your project? Short intro to Leiningen and Boot, with short code snippets. Links to the exact locations in their respective docs that talk about setting up and running (tutorial for Leiningen, Getting started for Boot)

• How to test your code? Short intro on how to setup tests, add test directories, sample test code. A link to a larger guide (or a blog post, or an article) on how tot test Clojure code. A separate mention of clojure.spec, and a link to a guide on spec.

Additional links or small intro sections on other topics: deployment, running, configuration etc.

[aadrian]

Add Gradle as an integration path too (alternative to lein and boot)? https://gradle-clojure.github.io/gradle-clojure/

Using Gradle, it's much easier for existing JVM projects to just adopt Clojure alongside (just like an extra library) the existing JVM (Java, Groovy, Scala) code, since projects from scratch are not an option in many cases.

[owenRiddy]

I've proposed some changes to the Getting Started page (#357) to provide orientation to a prospective lost beginner. The end result is still a little bit schizophrenic - neither the repl and deps_and_cli guides are written for a beginner who want to know what to type into a terminal - repl is a comprehensive but multi-page with no code on Page 1. deps_and_cli mixes libraries (more advanced topic, need to be comfortable with Clojure runtime model as a hosted language) with clj -m program.clj (very basic topic, needed to run a script) or clj (needed to do anything at all).

I'm also thinking the State of Clojure survey could be used strategically. Bringing a few graphs from Surveymonkey in to the main clojure site would give some helpful hints that CIDER/Emacs is the preferred IDE and that web development is a very well understood use case for Clojure.

[puredanger]

Thanks! I need some time to think through some of this more. Probably won't take this PR as I think there are bigger structural changes needed and I want to think about how this affects the visible link structure, some of which is pointed to by other places too.

[owenRiddy]

No worries. If you want to talk to a broader vision it will be interesting to hear - at the moment I can't see where a newcomer is going to get their hints on how to prioritise reading the documentation. I'm in agreement with dmitriid that the Deps & CLI guide is not well highlighted for something that is really quite urgent reading, at the moment it is just one of several hundred cross-links that can be found in guides & reference sections.

[puredanger]

I've been actively working on this area and the getting started page is now an entry point with more of an overview and pointers into different resources and installation has moved to a separate page. This is a work in progress and we have plans to add more of the things that you mention here about working in project context etc. I'm going to close this because I'm working off of other places on this but rest assured these ideas along with others are feeding into the approach.

[dmitriid]

Thank you! Even though I've moved on from Clojure, it's still nice to see documentation imoriving 👍👍👍