Closed rofrol closed 7 years ago
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 address0.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.
You are right about elm-reactor
. I even thought about it last evening but forgot to correct.
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
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:
Maybe we can simplify it to:
try in browser or locally:
in locally:
Later on we can inform about other possibilites like elm-make, elm-package, elm-architecture-tutorial, examples, etc.
Also for me http://elm-lang.org/get-started is to complex
There is also overlap between
Do we need this in three places?
I like the structure on https://rust-lang.org/. You have two main places:
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:
There is also box when you can try rust without leaving the frontpage and link to more examples beneath it.
Also the documentation is scattered all over the different places:
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.
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.
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.
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.elmelm.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 functionover9000
to Main.elm, I was confused that\
I couldn't just run function in next line
I had to get to output to some variable, but then I had to first declare the type of it
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
elm-package install evancz/start-app
. Maybe becausereactor
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.