Make the introduction more streamlined

[rofrol]

Heare are my steps that I've run through:

Go to http://elm-lang.org Go to http://elm-lang.org/install "Afterwards, visit the get started page" Go to http://elm-lang.org/get-started

elm reactor -a=localhost Go to http://localhost:8000/src/Main.elm

• it wasn't so obvious that I have to just open elm file in the browser
• elm.js appeared. What is it for?

"The easiest way to get started with Elm is from the Examples page" Go to http://elm-lang.org/examples

Back to http://elm-lang.org/get-started "In the documentation page on the website, you can find a bunch of resources on Elm" Go to http://elm-lang.org/docs "For beginners, I recommend starting with the Elm Complete Guide" Go to http://elm-lang.org/guide/core-language I run elm repl. I was confused that it doesn't indent after new line like in python repl and encountered this problem https://github.com/elm-lang/elm-repl/issues/67. After copy-pasting function over9000 to Main.elm, I was confused that

• I had to remove \

• I couldn't just run function in next line

  over9000 powerLevel =
  if powerLevel > 9000 then "upps 9000" else "meh"
  over9000 9001

• I had to get to output to some variable, but then I had to first declare the type of it

  a : String
  a = over9000 9001

Back to http://elm-lang.org/docs Go to http://elm-lang.org/docs/from-javascript Back to http://elm-lang.org/docs Go to https://github.com/evancz/start-app

• it has 4 links to https://github.com/evancz/elm-architecture-tutorial/
• No info that I have to run: elm-package install evancz/start-app. Maybe because reactor doesn't install deps as make?

Go to https://github.com/evancz/elm-architecture-tutorial/ "If you are new to reading Elm code, check out the language docs" Back to http://elm-lang.org/docs

After all these steps I've finally get the structure of docs, but there should be easier introduction page without jumping back and forth. Maybe some menu on the left indicating where we are at.

[jvoigtlaender]

Thanks for the feedback. Can you maybe make concrete proposals for changes to http://elm-lang.org/get-started? Before that, can you read it carefully again? My impression is that some of the things you mention as missing are actually already in there.

For example, you wrote, about elm-reactor:

Go to http://localhost:8000/src/Main.elm

• it wasn't so obvious that I have to just open elm file in the browser

but the section of the page about elm-reactor does already say the following:

Running elm reactor will open a web server on address 0.0.0.0:8000 where you can visit using a browser and select the file you want to run.

What else would the page have to say to forestall this specific question of yours?

Etc.

[rofrol]

You are right about elm-reactor. I even thought about it last evening but forgot to correct.

[rofrol]

There is also overlap of functionality between https://github.com/evancz/elm-architecture-tutorial/tree/master/examples/1 and https://github.com/evancz/start-app

Two examples that do the same

[rofrol]

My proposal is to clean README.md of https://github.com/evancz/start-app

Maybe unify https://github.com/evancz/elm-architecture-tutorial/tree/master/examples/1 and https://github.com/evancz/start-app

Don't point users at first to multiple directions.

As for quickstart we have these options:

• http://elm-lang.org/try
• elm-repl
• elm-reactor
• https://github.com/evancz/start-app
• https://github.com/evancz/elm-architecture-tutorial/

Maybe we can simplify it to:

try in browser or locally:

in locally:

• install node.js
• npm install -g elm
• start-app using elm-reactor

Later on we can inform about other possibilites like elm-make, elm-package, elm-architecture-tutorial, examples, etc.

[rofrol]

Also for me http://elm-lang.org/get-started is to complex

There is also overlap between

• http://elm-lang.org/docs/from-javascript
• http://elm-lang.org/guide/core-language
• http://elm-lang.org/docs/syntax

Do we need this in three places?

I like the structure on https://rust-lang.org/. You have two main places:

• https://doc.rust-lang.org/
• http://doc.rust-lang.org/book/

They point you to the book very early on the front page or in getting started in https://doc.rust-lang.org/#getting-started.

And thanks to the navigation tree on the left, you know exactly where you are in documentation.

On the frontpage they have four links to stable docs:

• Book
• Reference
• API docs
• All docs

There is also box when you can try rust without leaving the frontpage and link to more examples beneath it.

[rofrol]

Also the documentation is scattered all over the different places:

• web pages on http://elm-lang.org
• github projects like https://github.com/evancz/elm-architecture-tutorial
• gists https://gist.github.com/evancz/8521339

[jvoigtlaender]

Various reasonable proposals. You could write pull requests putting some of them into action, but I would advise to only do that if you get Evan's endorsement first. Otherwise, you might invest time for naught.

About http://elm-lang.org/get-started specifically: When it was put forth, the idea was that it would consist of post-install information on which tools are available and how to use them, not more. The learning stuff should be on a separate page. See also https://github.com/elm-lang/elm-lang.org/pull/379.

[rofrol]

I think this https://pragmaticstudio.com/blog/2014/12/19/getting-started-with-elm is quite good for introduction. It gradually shows you new commands. And also explains this type annotation Color -> Float -> For early on: .

Nicely shows why should I use |> etc.

[evancz]

The feedback here is helpful, thank you!

I'm not sure I can respond to everything mentioned in this thread, but I can at least say that a lot of progress has been made in smoothing out this path. A lot of documentation has been consolidated into guide.elm-lang.org. It has new information on reading types and using Elm in general. It also includes all the "get started" information.

So any links to installers will go directly to this page which also puts you at the beginning of the guide.

start-app no longer exists, partly because it was confusing that you had to know about it to do anything, so that should be smoother as well.

I think there are missed things, like the backslashes in the REPL, but that already has another issue open. So I think it makes sense to close this and if anything is missing, open a smaller issue about the specific missing thing.