search

elm / elm-lang.org

Server and client code for the Elm website.
http://elm-lang.org/
BSD 3-Clause "New" or "Revised" License
1.99k stars 365 forks source link

Add proper get-started-page (again?) #327

Closed jvoigtlaender closed 8 years ago

jvoigtlaender commented 9 years ago

The installers provide the link http://elm-lang.org/Get-Started.elm. Currently it redirects to http://elm-lang.org/docs, but that page does not really tell the user how to get started with Elm in terms of how to build/run a program.

How do I compile a program? What is elm-reactor, what are the roles of the other executables installed, etc.? These questions are not answered there, and as evidenced in this thread, this can be an impediment for people starting out.

I vaguely remember that there previously was a get-started-page that provided such info. Or maybe that was instead some README of one of the various repos? In any case, it seems worthwhile to have http://elm-lang.org/Get-Started.elm not be a redirect to http://elm-lang.org/docs, but instead a page with info about what got just installed (and then possibly a link from that page to http://elm-lang.org/docs). Incidentally, Gil Mizrahi's blog post pointed to in this thread fits the bill quite well. Maybe it's even possible to turn that post into something for http://elm-lang.org/Get-Started.elm?

chasm commented 9 years ago

The Reactivity tutorial provides lots of code. No idea where to put it. No idea how to start the app. No idea how to compile it.

No problem! I'll just use the handy contact form to . . . uh, oh. No contact form. No contact info. No link to GitHub. No nothing. Not even comments on the blog pages. The site exists in its own world, completely disconnected from the users.

I guess the Elm folks really want to keep the newbies out.

Epic fail. Absolutely epic.

soupi commented 9 years ago

@chasm though you do have a community tab with links to the mailing list, subreddit, IRC, twitter and github.

chasm commented 9 years ago

None of which are appropriate for a bug report.

Fail is fail. Best response is a mea culpa and a quick fix.

jvoigtlaender commented 9 years ago

Further evidence that adding something along the lines in my comment above may be a good idea.

jvoigtlaender commented 9 years ago

Another related post on the mailing list.

evancz commented 9 years ago

I wrote this at some point. It kind of covers things. The new elm-architecture-tutorial also does a better job.

Can you do a PR? I don't know the right thing, I guess something bad happened in Hackage recently so I am trying to deal with that right now. Maybe go through the repo history and revive the old page? Just do a PR and we can work from there.

jvoigtlaender commented 9 years ago

Is GitHub dropping comments? I had written one here explaining why I still think that Gil Mizrahi's blog post would be the best start here, and that I would ask Gil whether the willingness to make a PR from it is still there. (Which I have now done.)

jvoigtlaender commented 9 years ago

For the record: I don't know exactly what was on the original Get-Started page, and couldn't immediately locate it in the repo. But from the mailing list threads above it seems clear to me that something that should be on that page (and isn't currently in the starter.md linked above or on the elm-architecture-tutorial pages) is a description of what binaries are installed by the installers and what their roles are for Elm development. Let's wait for a pull request by @soupi, then work from there.

antonycourtney commented 9 years ago

I also encountered this and reported it in a post to the mailing list.

I cloned the repository and took a look through the history. It appears that the old Get-Started.elm page was (accidentally?) removed during a restructuring / cleanup of docs in a large commit done on Mar. 4 to "Remove all non-essential pages".

I agree with @jvoigtlaender that Gil Mizrahi's blog post is probably a better starting point for a Getting Started page.

@soupi : Are you up for submitting a PR for a new Getting Started page based on your blog post ? That would be super helpful to newcomers.

soupi commented 9 years ago

@antonycourtney : sure. though as I told @jvoigtlaender I will only be able to start working on this next week. In the meantime I have created a gist with the content of my blog post in markdown format (here). If you have any comments or suggestions feel free. I would also like to note that English is not my first language so it is likely that I will make some mistakes in this regard.

Gil

soupi commented 9 years ago

I have updated the gist by mixing and matching the old getting started page and my post, and created an elm file for the getting started page but haven't managed to get elm-website to compile yet so I could test it. Please review the document if you can. feedback is very much appreciated.

jvoigtlaender commented 9 years ago

Looks good! I spotted a few typos and would make a few suggestions for local changes. Maybe the easiest way to organize this is that you open a pull request against this repo, including that elm file in an appropriate location. I could then make pull requests against yours and you can incorporate as you see fit. I think I can also help (again by suggesting patches to a pull request opened by you) with integrating this into the website.

soupi commented 9 years ago

Alright, I'll try building the website again today (maybe with the beta no-reinstall cabal) and submit a pull request.

jvoigtlaender commented 8 years ago

I'm closing this issue, since it has been resolved by #370. Thanks, @soupi!