search

clojure / clojure-site

clojure.org site
https://clojure.org
Eclipse Public License 1.0
249 stars 270 forks source link

"Getting Started" area needs work #4

Closed puredanger closed 2 years ago

puredanger commented 8 years ago

There needs to be a better Getting Started page (probably actually more than one page) that covers:

johndenverscar commented 8 years ago

I really like your fourth point. A detailed and well maintained guide about how to set up a development environment in Emacs would be great. Especially for people who haven't used anything other than tools like Eclipse/IntelliJ which come ready to use with the click of a button.

It's difficult enough to learn a new language, trying to fumble around with a new tool, especially one like Emacs, just makes it that much more difficult.

yatesco commented 8 years ago

+1. The thing about emacs though is either you know it in which case a getting started guide is probably not necessary or you don't, in which case the getting started guide should be many miles of paper :-). I really like the approach in http://www.braveclojure.com/basic-emacs/.

lgrapenthin commented 8 years ago

(sorry for slightly off topic, please tell me where to move this)

The problem with Emacs is that Emacs is best learned separately from Clojure. Someone who has never used Emacs will perceive Emacs as an obstacle and disturbance while trying to learn Clojure. This experience has been reported many times. If you accidently hit C-x C-c because you try to copy paste, it closes and you think it crashed.

Also the guide linked by @yatesco is great, but it is a true overkill for someone with an attention span intended for trying out one of N new languages, maybe just out of curiosity. Ask yourself: Would you try out a different lang you have heard one or two interesting things about when it is going to take you at least half a day and 10+ tutorial screen pages to set up an editor for it? It leaves a totally wrong initial impression: "This lang feels like one never gets anything done with it".

IMO beginners should be presented one simple and clean way to try the lang that they can build upon. Ten links to ten IDEs/Editors/Plugins are a good thing, but outright confusing for starters.

Unfortunately, Cursive which I only heard good things about and which is supposed to be many more times beginner friendly than Emacs is going to become commercial, so that is not really an option.

Racket really profits from having their own IDE. You get that Download Racket->Try Racket->Learn Racket experience with no interruptions. IMO we should aim for that. Download Clojure->Use Clojure, but not just a command line REPL. Should feel like you are ready to go experiment with and experience the language.

What I'd propose is a curated "Clojure Starter package". An Emacs or Atom (? IDK Atom) that is configured for users who use a mouse and arrow keys. Let's configure it so that it looks and feels like minimalistic IDE, but with a file tree and a small menu with things like "Create Clojure Project" that non Emacs/Vim users feel comfortable with. Maybe even with some example code you can try right away. E. g. the examples on the current Getting Started page, Hickeys Game of Life impl, even a sample Clojure/ClojureScript Webapp and so on. A nice roundtrip showing off what you can do with Clojure in examples that you can try and modify right away. IMO this should be the aim: One download button->one or two clicks install->no errors->go. So it should have an install script that installs a JVM and Leiningen if necessary. Between 3 and 10 2-4m tutorial videos should come with it. If there is demand please let me know, I'd like to help.

yatesco commented 8 years ago

An alternative is to skip IDEs altogether and do something with REPLs embedded in the (HTML) guide itself. The getting started guide could then, at each relevant point have the embedded REPL for the user to enter the right stuff...

Now ClojureScript can host itself this should be significantly simpler.

I idly wonder whether devcards or gorilla REPL would be a good starting point...

Answering the 'this is what you need to know about Clojure' and 'this is how to use it in environment X' is, you know the word, say it with me: complecting concerns! (yeah for buzzword bingo)

edvorg commented 8 years ago

Hi. You could try Lighttable, it's quite good as a beginner's editor.

On Sat, Nov 14, 2015, 6:10 PM lgrapenthin notifications@github.com wrote:

The problem with Emacs is that Emacs is best learned separately from Clojure. Someone who has never used Emacs will perceive Emacs as an obstacle and disturbance while trying to learn Clojure. This experience has been reported many times. If you accidently hit C-x C-c because you try to copy paste, it closes and you think it crashed.

Also the guide linked by @yatesco https://github.com/yatesco is great, but it is a true overkill for someone with an attention span intended for trying out one of N new languages, maybe just out of curiosity. Ask yourself: Would you try out a different lang you have heard one or two interesting things about when it is going to take you at least half a day and 10+ tutorial screen pages to set up an editor for it? It leaves a totally wrong initial impression: "This lang feels like one never gets anything done with it".

IMO beginners should be presented one simple and clean way to try the lang that they can build upon. Ten links to ten IDEs/Editors/Plugins are a good thing, but outright confusing for starters.

Unfortunately, Cursive which I only heard good things about and which is supposed to be many more times beginner friendly than Emacs is going to become commercial, so that is not really an option.

Racket really profits from having their own IDE. You get that Download Racket->Try Racket->Learn Racket experience with no interruptions. IMO we should aim for that. Download Clojure->Use Clojure, but not just a command line REPL. Should feel like you are ready to go experiment with and experience the language.

What I'd propose is a curated "Clojure Starter package". An Emacs or Atom (? IDK Atom) that is configured for users who use a mouse and arrow keys. Let's configure it so that it looks and feels like minimalistic IDE, but with a file tree and a small menu with things like "Create Clojure Project" that non Emacs/Vim users feel comfortable with. Maybe even with some example code you can try right away. E. g. the examples on the current Getting Started page, Hickeys Game of Life impl, even a sample Clojure/ClojureScript Webapp and so on. A nice roundtrip showing off what you can do with Clojure in examples that you can try and modify right away. IMO this should be the aim: One download button->one or two clicks install->no errors->go. So it should have an install script that installs a JVM and Leiningen if necessary. Between 3 and 10 2-4m tutorial videos should come with it. If there is demand please let me know, I'd like to help.

— Reply to this email directly or view it on GitHub https://github.com/clojure/clojure-site/issues/4#issuecomment-156709953.

johndenverscar commented 8 years ago

If an all in one 'Quick Start' package is the goal, Lighttable or Night Code would be, I think, ideal. They provide an immediate start without having to work with config files. Both are Clojure projects, which is nice to boast, and they are very easy to use.

@lgrapenthin, I like the idea of small Clojure/CLojure Script projects for beginners

@yatesco, were you thinking about something like Try Ruby?

yatesco commented 8 years ago

@mzavarella30 Not exactly - that is a single REPL with moving instructions. I was thinking more like a separate REPL per point.

In other words, instead of the guide saying 'Enter the following into IDE X' it would embed a REPL right there. I am sure I have seen prior art but I can't find it...

I am trying to articulate my discomfit in the quick start guide depending on an editor and failing...it is something about:

The embedded REPL idea side steps all of that and makes it easier to 'get started'.

The getting started guide has to say something about actually typing stuff in, I just think it should be as un-opinionated as possible.

lgrapenthin commented 8 years ago

@yatesco Cognitect has created such a package with Gorilla. It is aimed at people who have programming experience https://github.com/cognitect/clojure-lab - It's definately worth adding.

Still IMO users need instant confidence and trust that they can use this on a day to day basis without even thinking about having to go through a myriad of complex configuration or having to pick an IDE/learn Emacs chords or whatever. Because they only will if they are really sold on the lang.

I have heard that people get serious work done with LightTable nowadays. http://jr0cket.co.uk/2015/01/tweaking-light-table-for-a-great-clojure-experience.html could help to create a bundle. And IMO the beginners experience does not have to be based on professional tooling to be real or honest. It is about giving a great impression how a professional workflow feels like. Of course one has to work for it long term, but at least one should be sold that it is really worth it. I say that because nowadays we have the coolest impressive awesome stuff like the reloaded Workflow, e. g. we could offer to alternate between N examples in one running JVM! We have things like fighweel that you fall in love with in a sec. But I guess few people ever get to experience these things because they never get them set up.

I outright disagree that giving a beginner a REPL and saying "this is all you need for now, type in these forms and learn" is the best we can do. While technicaly true, it only speaks to people willing to learn pedantically which I'd assume are a minority. Also, after ten or twenty forms entered into it, even the last ones will ask "Ok this is cool, but how do I build a webapp?" and whatever they find on Google will set them back to square 0 which is unpleasant. A few examples that you can alternate between and run and modify locally right away should reach far more people.

yatesco commented 8 years ago

There is nothing stopping you ignoring the inbuilt REPL and using your editor of choice. Getting that editor setup should be trivial because of the other ’excellent setting up your environment’ links.

The problem boils down to whichever IDE you chose to base the getting started around is not going to be the one used by everyone, and therefore for everybody but the (probably) minority who will actually use the proposed IDE you are obscuring the interesting stuff (Clojure) with irrelevant stuff (using the IDE). I don’t think it is about learning styles, it is about removing distraction for those who are invested in an IDE. Again, I think we are conflating the needs of those who are new to programming and have no IDE with those who are very invested in their IDE and will find any other IDE a barrier.

I absolutely agree the value of “how to use Clojure to build …”.

Maybe a ‘Getting started’ and a separate document working through the ‘Getting started with IDE-X’.

On 14 Nov 2015, at 16:20, lgrapenthin notifications@github.com wrote:

@yatesco https://github.com/yatesco Cognitect has created such a package with Gorilla. It is aimed at people who have programming experience https://github.com/cognitect/clojure-lab https://github.com/cognitect/clojure-lab - It's definately worth adding.

Still IMO users need instant confidence and trust that they can use this on a day to day basis without even thinking about having to go through a myriad of complex configuration or having to pick an IDE/learn Emacs chords or whatever. Because they only will if they are really sold on the lang.

I have heard that people get serious work done with LightTable nowadays. http://jr0cket.co.uk/2015/01/tweaking-light-table-for-a-great-clojure-experience.html http://jr0cket.co.uk/2015/01/tweaking-light-table-for-a-great-clojure-experience.html could help to create a bundle. And IMO the beginners experience does not have to be based on professional tooling to be real or honest. It is about giving a great impression how a professional workflow feels like. Of course one has to work for it long term, but at least one should be sold that it is really worth it. I say that because nowadays we have the coolest impressive awesome stuff like the reloaded Workflow, e. g. we could offer to alternate between N examples in one running JVM! We have things like fighweel that you fall in love with in a sec. But I guess few people ever get to experience these things because they never get them set up.

I outright disagree that giving a beginner a REPL and saying "this is all you need for now, type in these forms and learn" is the best we can do. While technicaly true, it only speaks to people willing to learn pedantically which I'd assume are a minority. Also, after ten or twenty forms entered into it, even the last ones will ask "Ok this is cool, but how do I build a webapp?" and whatever they find on Google will set them back to square 0 which is unpleasant. A few examples that you can alternate between and run and modify locally right away should reach far more people.

— Reply to this email directly or view it on GitHub https://github.com/clojure/clojure-site/issues/4#issuecomment-156716762.

lgrapenthin commented 8 years ago

I fully agree. But I find it a valid solution to say: Here is a very easy to use IDE like LightTable that you can instantly use and experiment with. I agree with you that it should NOT obscure learning Clojure so that is why I find it worth to create a package. It reaches everybody and pro IDE-X user can say: Cool, so I can really try the full deal of this and /then decide/ whether I want to go through some tutorial for my IDE. Consider that there are also people using IDEs that are not supported by Clojure. They'd feel excluded. Imagine a C++ dev coming from MSVS, he will be presented a choice he doesn't feel comfortable making at this point of time.

What I find worth maximixing for a first impression is: Lowest investment possible for the user (= Download Install Run at max), High impression and fun interactive experience with something awesome running in Clojure - aka "Here is a program you can modify and see the changes immediately. For instance try this, or try that" Instead of "Here are Clojure data types (chart). Enter a number at the REPL and it will be returned to you. Know what? It's self-evaluating..." There are tons of tutorials doing that for people who are ready to fully dive in.

puredanger commented 8 years ago

There will be no single IDE that is best for everyone.

I would like to have:

htmfilho commented 8 years ago

Did anyone started improving the "Getting Started" page? I would like to propose something if nobody is working on that.

johndenverscar commented 8 years ago

@yatesco, how in depth do you think the 'In browser REPL' tutorial would go?

yatesco commented 8 years ago

Sorry @mzavarella30 I missed your question. I dunno - I am merely suggesting that a browser REPL immediately removes the whole question of which IDE. Maybe devcards is a way forward here - for example: https://awkay.github.io/om-tutorial/

lxsameer commented 7 years ago

I would love to do this, is that ok @puredanger ? In order to keep it up to date with other people opinions I can make a work in progress PR and the improve the guide until it seems good enough to be merged.

puredanger commented 7 years ago

Actually, I am in the process of rewriting this page to use the new clj script that will released as part of Clojure 1.9 (and will also work for 1.8). There will undoubtedly be more to do when I'm done, but I think it makes sense to defer until I get through the initial chunk of rearrangement.

I'm not sure anyone has actually noticed it yet but there is a whole new set of pages now under "Learn Clojure" that I have been working on as well. I've got another 5 pages of material still to post there.

lxsameer commented 7 years ago

@puredanger Yeah I saw them. Kudos. But I general i think it would be awesome if we can break down the Learn Clojure topic to smaller pieces and combine them with the getting started guide and put all of them under the topic Getting Started instead of Learning

puredanger commented 2 years ago

Work is ongoing in this area, but closing this old issue