Feedback on initial setup experience

[Antony Courtney]

Hello!

I toyed with Elm briefly a couple of years ago, and am interested in trying it again now that HTML is more fully supported.

Unfortunately I got bit by a couple of issues with my initial installation.

Here is an account of what I've experienced so far.  I try to provide details and some constructive suggestions.

I started out at http://elm-lang.org/ :

• Obvious actions are 'try' and 'install'
  
• I'm 'serious' about wanting to use Elm, so I choose 'install'...
  

Install attempt #1 -- npm:

The Install page (http://www.elm-lang.org/install) indicates there is an officially supported npm installer.  Great!  I use npm regularly in other JS projects and have had good experiences with it. Using npm should allow me to do project local installs and easily and systematically upgrade my elm installation.

So:

• I proceed to npm installer page (https://www.npmjs.com/package/elm) and follow the instructions.
  
• Get a post-install test failure.
  
• Search for and add my comment to the relevant open issue here: https://github.com/kevva/elm-bin/issues/28
  
• Seems to be a simple missing binary and there's some advice there to maybe use the official Mac installer instead
  
• This issue has been open since Jul 9. There seem to be a number of people commenting on the issue but nothing that I can see looks like a response from a maintainer.
  
• Suggestion:  If the npm installer is either not official or not maintained I suggest either removing it from http://www.elm-lang.org/install or at least clearly indicating it's unoffical / unmaintained.
  

Install attempt #2 -- official Elm Platform installer packager:

• Downloaded and ran the official Elm Platform installer.
• All went OK with the Install.  At the end of the Installer, get to a "Summary" screen with the text:

A bunch of useful programs were just placed in /usr/local/bin/
Check out this tutorial to learn how to use them!

Respectfully "A bunch of useful programs" falls a little short of the level of developer-friendly useful detail that Elm prides itself on with its compiler error messages!  :-)

• Following the link labeled "this tutorial" from the Installer summary opens http://elm-lang.org/docs
  
• That docs page provides docs on the Elm language and how to write Elm programs.  It doesn't provide any information on what programs were installed or even minimal man-page style notes on how to use them...
• Suggestion:  Expand the text in the Installer Summary to at least name the programs that were installed.  Provide a simple page for those who've chosen the install option that gives a terse description of what each installed program is and where to go for more info. Provide a minimal worked example of a basic HTML app in Elm (the Counters example from the Elm architecture or TodoMVC perhaps?), and what commands are needed to compile and run.

Initial teething step #1: Trying to get a basic example (TodoMVC) compiling and running....:

• I faintly recall from the npm page that one of the programs was 'elm-make'.
• I google 'elm-make', check out the README in https://github.com/elm-lang/elm-make and yeah, this seems like what I want, but still doesn't help me with an example...
• I go back to the elm home page ( http://www.elm-lang.org/ ), scroll down to Examples, click through to the source link for todomvc (https://github.com/evancz/elm-todomvc).
• I clone this repo, and run 'elm-make':

$ elm-make

Some new packages are needed. Here is the upgrade plan.

  Install:

    elm-lang/core 2.1.0

   evancz/elm-html 3.0.0

   evancz/virtual-dom 1.2.3

Do you approve of this plan? (y/n) y

Downloading elm-lang/core

Downloading evancz/elm-html

Downloading evancz/virtual-dom

Packages configured successfully!

Success! Compiled 36 modules.                                      

Gamma:elm-todomvc antony$

• I then try opening 'index.html' in my browser, but got a 404 loading 'elm.js'.
• Confused, I try running 'elm-make' again:

$ elm-make

Success! Compiled 0 modules.                                        

Gamma:elm-todomvc antony$

• That didn't resolve the 404 errors opening 'index.html'....
• It turns out my issue here was doing an unqualified 'elm-make' when I needed to do 'elm-make Todo.elm'. D'oh! My mistake!  But...
  
• Suggestion: I think this bit of beginner confusion could be avoided if 'elm-make' run without arguments would either (a) build the primary or default target in the current directory or (b) give an explicit error indicating that the user must supply a valid target to build.  IMO (a) is friendlier and more consistent with other build tools like make, gulp, etc., but even (b) seems preferable to the current behavior, which seemed to do 'something' (on the first run), but nothing very useful.

The happy news is that when I finally ran 'elm-make Todo.elm' on this example, things worked the way I'd hoped!  Yay!

My hope in writing the above is that a tiny bit of work will make it much easier for an experienced front end developer new to Elm to get up and running.  Hope the above suggestions are helpful. Happy to review any proposed docs; sorry I'm not in a position to write them myself yet.

Thanks for Elm!

    -Antony

 

 

 

 

[Janis Voigtländer]

The problems mentioned after “Install attempt #2 — official Elm Platform installer packager:“ (i.e., what to do after having installed Elm with one of the installers) are what this issue is about.

​

--
You received this message because you are subscribed to the Google Groups "Elm Discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elm-discuss...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Antony Courtney]

Ah, that's perfect.  I've added a comment on the issue.  Thank you for creating and documenting the issue in such detail and for pointing me to it.

[Gil Mizrahi]

This is really great feedback. Thank you both for taking the time and trying to improve the system!