Optimizing initial experience on haskell.org for the first-time Haskell user

[Martinsos]

Hi,
I am opening this issue as advised by @tomjaguarpaw , following up on the discussion I started on Haskell Foundation Slack.

I have been using Haskell for years but few days ago I wanted to check what is the current recommended way to install Haskell, hoping I might clean up my mess that somehow works but I can't even remember how I set it up (I am on ArchLinux, using Stack, didn't use ghcup so far).

In this process I actually ended up having a hard time figuring out what is the current recommended approach, which is I am writing this.

My journey

I went to haskell.org first, but didn't see any obvious link/button that would guide me to setting up Haskell on my machine. I did see the "Downloads" link in the top navbar, but it wasn't emphasized in any way, and I usually expect from "Downloads" to be a list of binaries, which wasn't what I was looking for, I was looking for a "Getting started" kind of thing that will take me through the process of setting up Haskell.

I scrolled through the whole webpage and saw link to Haskell wiki at the bottom, so I concluded that might have section "Beginners" or "Getting started" or smth and I clicked on that.

On haskell wiki I saw catchy orange "Download Haskell" button on haskell wiki. That button took me to haskell.org/platform, where I went through some technical noise (details about stack upgrade and libgmp) to at the end learn that I should install ghcup and stack.

I then went to haskell.org/ghcup to learn that ghcup also installs stack, so started wondering if I should install stack via ghcup or if I should do it separately as previous instructions said.

At that moment I concluded this is all getting too complicated and maybe I went the wrong way, so I went back to haskell.org because I remembered I saw "Downloads" there, and maybe I should have clicked on that. "Downloads" took me to instructions that sent me to haskell.org/ghcup again.

At this point I gave up for now because I wasn't sure if I should use ghcup to install Stack or not, and I was also afraid it might mess up my hls (does ghcup do the "wrapper" thing to pick correct hls based on project? I wasn't sure), and decided to come back to it once I do more research and have more time.

Thoughts

haskell.org -> "Downloads" -> haskell.org/ghcup is not a bad journey, but it still feels somewhat weird, as "Downloads" is in no way emphasized, and when I end up at ghcup page it feels a bit like this is a third-party project due to different webpage design and style. Plus, top part of GHCup home page is pretty complex and feels more aimed at contributors than first time users.

I know that comparisons with Rust are often made, but it seems to me that they did this right: they have a big yellow "Get Started" button on the top of the homepage, impossible to miss.
That button takes you to the page where almost immediately they tell you to use rustup to install rust (no big intro on rustup like ghcup has, just a couple of sentences and then a command to install it / run it), give you a bit of details on the toolchain, follow up with a super short tutorial to get something working and then send you off to the book/tutorials/examples.
I would imagine that Haskell could also benefit from such direct, guided journey for the new users!

Ideas

Here is how I see possible steps to improving experience of getting started with Haskell, ordered by benefit/complexity ratio:

1. Add a big, visible "Get Started" button above the fold on haskell.org home page that just sends user to haskell.org/downloads. "Try it!" interactive section is already occupying a lot of space hm, but easiest thing might be to insert a new section above the "Try it" which would have a big button on the middle that says "Get Started" or "Install Haskell". Or, it could go under the code example on the right + we would add some spacing under the "Haskell - An advanced ..." piece. Besides Rust page, another example could be project I am working on, https://wasp-lang.dev/ -> we put the "Try it" button right under the title and code example, and it takes you to installation instructions.
2. Streamline Downloads page just a bit more:
   Make "Installation instructions" section more prominent, since it is the main call to action we want them to take -> if there is one thing they will see first on this page, it should be that section. It doesn't mean it has to be first section, but we could for example apply some spacing around it, put some kind of border to emphasize it, maybe change the background color to purple (Same as there is "Try it" on the home page).
   Figure out if we should recommend installing stack separately or not.
3. Make haskell.org/ghcup page feel more "official" -> either by saying it is "recommended" / "official" installer, or by using the same design as on haskell.org.
4. Ultimate solution: Create "Getting started" page to which the "Get started" button on haskell.org home page will lead, instead to "Downloads". It would start with short instructions on how to install ghcup, then help you create your very first project and run it, maybe super shortly explain what is stack/cabal/hackage, but in practical way, then quickly cover what is the support like in the editors and which editors are most popular (so I guess covering vscode, vim, emacs would already be enough) and then finally forward you to the further materials for learning with clear path of progress (so instead of huge list of books, there would be an opinionated suggestions on the reading order). Again, I think Rust did this really well with https://www.rust-lang.org/learn/get-started .

Guiding principles

The main idea behind this is that at every step in this journey, it should be very clear what is the next recommended step, and user's focused should be kept on it.

So if there are multiple buttons on the screen, the one that is recommended should be somehow emphasized. Less buttons/links also helps.

If there are multiple pieces of information that might be interesting, the one that is most likely to be important should again be put in focus -> e.g. if we send them to ghcup to install it, installation instructions should be more prominent than list of communities or even GIF showing how ghcup works -> we don't want them to join ghcup Discord at this point, we want them to install ghcup. We also don't need them to look at the GIF of ghcup, it doesn't serve any purpose, they came here anyway to install it and GIF won't convince them further. rustup.rs is great example of this, page is very clean and minimal, with installation instructions emphasized, and list of communities at the bottom and additional resources at the bottom.

[jneira]

Pinging @hasufell for the ghcup part but want to note there was a pr to simplify download instructions, prioritizing ghcup, now closed pr due to techno-political reasons.
Add a getting started button is a must imho, not sure how could be designed to get consensus.

[tomjaguarpaw]

This is tremendously helpful, thank you so much @Martinsos! I don't have time to respond in detail now but I will get back to you as soon as I can. I think we probably need to gather a group of people willing to discuss and work on this issue to hammer out what would be the best new user experience for obtaining Haskell. Experience reports like this are one of the most valuable pieces of information we have.

[Martinsos]

Awesome @tomjaguarpaw , I am glad it helps!
Let me know if I can further help in any way -> I have some experience with designing web pages and docs for my tools / projects / startups in the past and I personally care about user journey a lot, so I would love to see this improved for Haskell and help how I can. I am also now leading a company that will he hiring developers that will be learning Haskell for the first time and I would love to be able to send them to the official docs instead of me designing a document with instructions on how to get started with Haskell (and as is state right now, I would certainly do the second).

p.s. when I say designing I don't mean making it beautiful but instead organizing content so it guides the user as was intended.

[Martinsos]

Oh, and regarding experience reports -> this one that I described is me kind of pretending I am using Haskell for the first time. But it would be much more valuable to get the same kind of report from actual first-time users! Not sure what is the best way to get those, possibly get some volounteers who never tried Haskell to give it a go. I usually reach out to friend and ask them to try and install my tool while I am watching them as they share the screen, and then I write down the whole experience. Maybe you could ask on Functional Programming Discord, or on Programming reddit, for peple to take a look at haskell.org and write down their feedback.

[hasufell]

I then went to haskell.org/ghcup to learn that ghcup also installs stack, so started wondering if I should install stack via ghcup or if I should do it separately as previous instructions said.

https://www.haskell.org/ghcup/about/#why-should-i-let-ghcup-manage-stack

At this point I gave up for now because I wasn't sure if I should use ghcup to install Stack or not

I'm not sure I can follow here. If you're unsure, then just install stack the way it's recommended on the https://www.haskell.org/downloads/ page: "To install stack, follow the instructions here"

The Haskell Foundation requested this feature (as part of the tech track about unified installer, which failed).

and I was also afraid it might mess up my hls (does ghcup do the "wrapper" thing to pick correct hls based on project? I wasn't sure)

ghcup installs haskell-language-server-wrapper, yes.

and when I end up at ghcup page it feels a bit like this is a third-party project due to different webpage design and style.

GHCup is supported by haskell.org and Haskell Foundation. I'm not sure what you mean with "third-party". It's run by the GHCup developers, yes: https://www.haskell.org/ghcup/about/#team

Plus, top part of GHCup home page is pretty complex and feels more aimed at contributors than first time users.

What is complex about it?

Compare with stack and cabal:

• https://docs.haskellstack.org/en/stable/README/
• https://cabal.readthedocs.io/en/latest/

I'd argue GHCup homepage is much more friendly.

I know that comparisons with Rust are often made, but it seems to me that they did this right: they have a big yellow "Get Started" button on the top of the homepage, impossible to miss.

The old ghcup homepage was a clone of https://rustup.rs/ ...see here https://imgur.com/x7C1xY3.png

The new homepage is much more informative.

That button takes you to the page where almost immediately they tell you to use rustup to install rust (no big intro on rustup like ghcup has, just a couple of sentences and then a command to install it / run it)

Can't follow here.

1. ghcup has a pretty big button "Quick Install" that takes you to the install instructions straight away. It's literally two clicks and then paste in your terminal: https://www.haskell.org/ghcup/#quick-install
2. "big intro"? Where?

give you a bit of details on the toolchain

Like this? https://www.haskell.org/ghcup/install/#supported-tools

follow up with a super short tutorial to get something working

Like this? https://imgur.com/1CHtfnm.png

and then send you off to the book/tutorials/examples

Yeah sure, could do that too, but we don't have a definite community agreed upon tutorial.

Make haskell.org/ghcup page feel more "official" -> either by saying it is "recommended" / "official" installer, or by using the same design as on haskell.org.

It is recommended, because https://www.haskell.org/downloads/ says: "Install GHC, cabal-install and haskell-language-server via GHCup". I think that's clear enough?

Wrt the design: I don't think I want GHCup homepage to look like the downloads page. It looks confusing and messy.

Create "Getting started" page

Sounds like #88 which was abandoned due to lack of approval/review by the haskell.org committee.

[hasufell]

Also: https://www.haskell.org/documentation/

[hasufell]

https://gitlab.haskell.org/haskell/ghcup-hs/-/merge_requests/201

Edit: updated page is live https://www.haskell.org/ghcup/

[Martinsos]

Thanks for detailed response @hasufell !

Just to give a bit of context: while I was providing feedback, I wasn't trying to say that there is no way for me to figure out certain things without taking more time and doing more research -> I believe I would be able to answer most of the questions if I dedicated more time to it, thanks to the materials available online. What I was focusing on is the experience that one has when having limited time / focus while checking out the new technology, in this case Haskell, and the vibe that this technology gives regarding ease of usage and approachability.
I greatly value the effort you took to provide me with answers regarding some of the questions I asked in my feedback, although the point was not for me in particular to get those answers, but to figure out how to modify the journey of a Haskell newcomer such that those questions never arise / are answered immediately.

I then went to haskell.org/ghcup to learn that ghcup also installs stack, so started wondering if I should install stack via ghcup or if I should do it separately as previous instructions said.

https://www.haskell.org/ghcup/about/#why-should-i-let-ghcup-manage-stack

At this point I gave up for now because I wasn't sure if I should use ghcup to install Stack or not

I'm not sure I can follow here. If you're unsure, then just install stack the way it's recommended on the https://www.haskell.org/downloads/ page: "To install stack, follow the instructions here"

Hm I feel like you are telling me if I am unsure if option A or option B is correct, I should use option B.

To draw a somewhat silly analogy -> if I am building a house and I ask expert for advice on how to build it, and he tells me I should have person X take care of everything except for the roof, and have person Y do the roof, and then person X tells me he can also take care of the roof, I would have hard time deciding if I should let the person X do the roof or give it to person Y.
On the one it sounds tempting to have person X do also the roof, since they are doing everything else and there is less chance for misscomunication and possible misalignments, but on the other hand why was I told about person Y then? Maybe the expert didn't know that X also does roofs? Or they knew but thought that Y will do it better? Well, I don't know, I would have to go and consult the expert again. However with Haskell I don't have any option but to ask somebody and that will take much more time then than I expected.

The Haskell Foundation requested this feature (as part of the tech track about unified installer, which failed).

Which feature -> having ghcup install stack? Too bad if that failed -> but if it failed, how is it that ghcup is offering to install stack?

and I was also afraid it might mess up my hls (does ghcup do the "wrapper" thing to pick correct hls based on project? I wasn't sure)

ghcup installs haskell-language-server-wrapper, yes.

Cool, didn't know that. Fair point here would be that newcomer probably wouldn't know enough about hls to even worry about this, so this piece of info is probably not that important for them.

and when I end up at ghcup page it feels a bit like this is a third-party project due to different webpage design and style.

GHCup is supported by haskell.org and Haskell Foundation. I'm not sure what you mean with "third-party". It's run by the GHCup developers, yes: https://www.haskell.org/ghcup/about/#team

By third party I mean that it is not an official tool. Kind of like pacman is official package manager for archlinux, but yay or any other AUR helper is not. I usually try to stick with official tools when starting out with new piece of tech.

Plus, top part of GHCup home page is pretty complex and feels more aimed at contributors than first time users.

What is complex about it?

When designing a webpage, one designing it should ask themselves -> what do I want the visitor of the webpage to learn / do?

Answer to this question depends on who the visitor is! As I said above, right now it feels like right now this page is aimed for contributors / existing users, not for newcomers.

So when I come to ghcup home page, I see 9 prominent buttons and 6 links, not counting the navbar! And there is also GIF there, demanding my attention. This is what I mean by complex.

The thing is, all of these buttons are pretty emphasized (prominent colors, centered) and it is a lot of information to grasp at once.

Ok, dismissing the first row is not that hard, I can quickly see those are communities and donating -> as a newcomer, all of those are too early for me, I am here merely to install ghcup. I might need support later (I hope not though) and I might donate even later.
But, if first row is not important to newcomers, then it shouldn't be here. It makes much more sense to for existing users / contributors.

Let's look at 4 purple buttons. Quick Install vs Getting Started -> both sound like same thing to me, I would have hard time figuring out which one to click of those two. So probably one is redundant. User Guide -> ok, nice but not for a newcomer I guess, it sounds like it is something that should come after Getting Started. So it should be in the navbar (which it is), and it should be present at the end of whatever content Getting Started will take me to. Issue Tracker -> not something I need right now or any time soon. I see Gitlab at the top anyway, I would go there if I needed to report an issue or search existing ones.

Gif -> what purpose does it serve? I came here to install ghcup, I don't see how GIF is going to change anything.

So, sounds like for a newcomer, all we need is a button that takes us to Getting Started -> meaning that we shouldn't be even sending newcomers to the ghcup home page, we should be sending them directly to https://www.haskell.org/ghcup/install/ (which is where Getting Started button leads to), and home page of ghcup is really meant for contributors / existing users. Which might be completely fine, but then we shouldn't send newcomers here.

Compare with stack and cabal:

• https://docs.haskellstack.org/en/stable/README/
• https://cabal.readthedocs.io/en/latest/

I'd argue GHCup homepage is much more friendly.

Stack has a good start actually, better than ghcup I would say -> they quickly say what Stack is and then tell you how to install it. Then goes quick start guide, starting a new project, further resources -> it is certainly aimed for newcomers and it follows a clear path. So it is pretty good actually I think.

That link to cabal just leads me to index, where I have to make a decision on what to click next, which is not great, but if I just click on the very fist link it takes me to https://cabal.readthedocs.io/en/latest/getting-started.html which is also pretty straight forward, has a clear path that consists of small steps and then further recommends how to progress. So I would argue this is also better than home page of ghcup (at least as an experience for newcomers).

I know that comparisons with Rust are often made, but it seems to me that they did this right: they have a big yellow "Get Started" button on the top of the homepage, impossible to miss.

The old ghcup homepage was a clone of https://rustup.rs/ ...see here https://imgur.com/x7C1xY3.png

The new homepage is much more informative.

It indeed is more informative! But most of that information is not important for newcomers, so if it is used as a place where newcomers should get started with using ghcup, then that information becomes a deterrant.

That button takes you to the page where almost immediately they tell you to use rustup to install rust (no big intro on rustup like ghcup has, just a couple of sentences and then a command to install it / run it)

Can't follow here.

1. ghcup has a pretty big button "Quick Install" that takes you to the install instructions straight away. It's literally two clicks and then paste in your terminal: https://www.haskell.org/ghcup/#quick-install
2. "big intro"? Where?

Explained above.

give you a bit of details on the toolchain

Like this? https://www.haskell.org/ghcup/install/#supported-tools

Sure, but this is different page, you need to get there. Rust has all of this inside one page. Same as stack and cabal have in those links you sent to me.

follow up with a super short tutorial to get something working

Like this? https://imgur.com/1CHtfnm.png

and then send you off to the book/tutorials/examples

Yeah sure, could do that too, but we don't have a definite community agreed upon tutorial.

Yes, that is tricky! I guess that is not something that can be taken care of easily, and probably shouldn't be part of this discussion.

Make haskell.org/ghcup page feel more "official" -> either by saying it is "recommended" / "official" installer, or by using the same design as on haskell.org.

It is recommended, because https://www.haskell.org/downloads/ says: "Install GHC, cabal-install and haskell-language-server via GHCup". I think that's clear enough?

Good point! That is true, and logically it makes sense, but still when I went to ghcup I felt like I was being sent "outside" of official haskell experience. This is not a biggie, take it with a grain of salt.

Wrt the design: I don't think I want GHCup homepage to look like the downloads page. It looks confusing and messy.

I think it all comes down to what is the purpose of the ghcup homepage. If it is there to give an overview of ghcup from all of its sides: community, donating, different documentation options, ... , then the current homepage makes sense. If the purpose is to get a person to get started with the ghcup for the first time, then it makes more sense to make it look like a download page with a big curl command in the center.

The simplest solution would be to keep ghcup page as it is, just change the link at https://www.haskell.org/downloads/ so it takes the user to https://www.haskell.org/ghcup/install/ instead of https://www.haskell.org/ghcup .

Create "Getting started" page

Sounds like #88 which was abandoned due to lack of approval/review by the haskell.org committee.

Ah too bad that failed! Although, I would argue that one is a bit too detailed for a getting started page, and it's title is actually "Learn about the core tools". Which sounds more like a page in the user guide that dives deeper into the tooling. I would imagine getting started to be more about: let's get newcomer quickly set up and have them achieve their first "win" -> get something cool done. Each next step needs to be just a bit more complex, and after it the next step has to be clear.
Cabal's https://cabal.readthedocs.io/en/latest/getting-started.html is not bad here -> each step achieves something new, there is almost no theory, just practice, and by the end I feel like I grasped the basic usage of cabal and did everything I might need to do for a simple project I want to start using cabal with.

[hasufell]

What I was focusing on is the experience that one has when having limited time / focus while checking out the new technology, in this case Haskell, and the vibe that this technology gives regarding ease of usage and approachability.

I guess I disagree with you then. Whether installing GHC takes 2 or 3 clicks is a nitpick imo. The biggest problem is indeed up-to-date learning material. Things like website design etc. are about how flashy and cool we can look and I don't consider any of that a real entry-barrier. I've seen far worse in other ecosystems. Installing python on windows used to be an odd journey for example.

Hm I feel like you are telling me if I am unsure if option A or option B is correct, I should use option B.

No, the page very clearly states two steps to install the Haskell toolchain. I'm really at loss how that can be misinterpreted.

I don't understand your house building analogy (I'm a trained brick layer), I'm sorry. But if you're asking about the cabal vs stack dilemma: I don't believe that's gonna be solved any time soon.

Which feature -> having ghcup install stack? Too bad if that failed -> but if it failed, how is it that ghcup is offering to install stack?

No, a unified installer (and hence proper integration with stack). I'll link the FAQ page again, which links to a stack PR that would fix most of these issues: https://www.haskell.org/ghcup/about/#why-should-i-let-ghcup-manage-stack

By third party I mean that it is not an official tool. Kind of like pacman is official package manager for archlinux, but yay or any other AUR helper is not. I usually try to stick with official tools when starting out with new piece of tech.

A distro can't really be compared to an entire open-source ecosystem. There's nothing really "official" about GHC even. It's just a compiler. If you write a better one tomorrow, people will likely switch. Haskell isn't run by a company (like rust used to be).

So I'm not sure what else we can do here.

Answer to this question depends on who the visitor is! As I said above, right now it feels like right now this page is aimed for contributors / existing users, not for newcomers.

Totally disagree with you. The homepage is directed towards users, just like stack and cabal. I'll link to those pages again:

• https://docs.haskellstack.org/en/stable/README/
• https://cabal.readthedocs.io/en/latest/

These are pretty dense in information as well. If you have concrete ideas about how to improve the page UI, please provide a PR. I don't think long discussions about website design are productive. We've also updated the design of the homepage today, making the download instructions more prominent: https://www.haskell.org/ghcup/

Gif -> what purpose does it serve? I came here to install ghcup, I don't see how GIF is going to change anything.

I feel like I'm running around in circles a little bit. The point of all this was that other users complained they don't really know what ghcup is or does on their machine, when all they see is an instruction they are supposed to copy into their terminal, see here: tomjaguarpaw/tilapia#92

I'm going to accept that I won't satisfy all users. And I'm confident that showing more information is necessary.

Stack has a good start actually, better than ghcup I would say -> they quickly say what Stack is and then tell you how to install it.

Ok, now ghcup has too little info? I feel your points are contradictory: you want the old page back that had zero information on what ghcup is or does, but find the stack homepage more informative. You can't have both.

[Martinsos]

https://gitlab.haskell.org/haskell/ghcup-hs/-/merge_requests/201

Edit: updated page is live https://www.haskell.org/ghcup/

Wow you did it! It looks great!

I would probably pull "Need help" section above the GIF, next to "Donate", so it is above the fold. It is discrete enough not too draw to much attention, but gives the visitor an idea where they can go later if they get a problem. Another reason to remove the "Issue Tracker" button is that you already have "report a bug" here.

Interesting question now is: what is the relationship between homepage and Getting Started page? I would say that they both serve same purpose but getting started gives more details. So for "lazy people" you want them to just copy paste the command on home page and go with that, but ideally they would come back to Getting Started at some point after that, right?

If so, then "Getting Started" should be the second most prominent call to action (CTA) on this page.
I would argue that "Issue tracker" is redundant next to the Gitlab in the top right corner and there is also a "report a bug" link, so "Issue tracker" button could be removed.
"User guide" -> it could be kept, but it is not as important as "Getting Started", so potentially it could be a bit less prominent, maybe use reverse colors: white background, purple letters.

[Martinsos]

What I was focusing on is the experience that one has when having limited time / focus while checking out the new technology, in this case Haskell, and the vibe that this technology gives regarding ease of usage and approachability.

I guess I disagree with you then. Whether installing GHC takes 2 or 3 clicks is a nitpick imo. The biggest problem is indeed up-to-date learning material. Things like website design etc. are about how flashy and cool we can look and I don't consider any of that a real entry-barrier. I've seen far worse in other ecosystems. Installing python on windows used to be an odd journey for example.

Hm I feel like you are telling me if I am unsure if option A or option B is correct, I should use option B.

No, the page very clearly states two steps to install the Haskell toolchain. I'm really at loss how that can be misinterpreted.

I don't understand your house building analogy (I'm a trained brick layer), I'm sorry. But if you're asking about the cabal vs stack dilemma: I don't believe that's gonna be solved any time soon.

Which feature -> having ghcup install stack? Too bad if that failed -> but if it failed, how is it that ghcup is offering to install stack?

No, a unified installer (and hence proper integration with stack). I'll link the FAQ page again, which links to a stack PR that would fix most of these issues: https://www.haskell.org/ghcup/about/#why-should-i-let-ghcup-manage-stack

By third party I mean that it is not an official tool. Kind of like pacman is official package manager for archlinux, but yay or any other AUR helper is not. I usually try to stick with official tools when starting out with new piece of tech.

A distro can't really be compared to an entire open-source ecosystem. There's nothing really "official" about GHC even. It's just a compiler. If you write a better one tomorrow, people will likely switch. Haskell isn't run by a company (like rust used to be).

So I'm not sure what else we can do here.

Answer to this question depends on who the visitor is! As I said above, right now it feels like right now this page is aimed for contributors / existing users, not for newcomers.

Totally disagree with you. The homepage is directed towards users, just like stack and cabal. I'll link to those pages again:

• https://docs.haskellstack.org/en/stable/README/
• https://cabal.readthedocs.io/en/latest/

These are pretty dense in information as well. If you have concrete ideas about how to improve the page UI, please provide a PR. I don't think long discussions about website design are productive. We've also updated the design of the homepage today, making the download instructions more prominent: https://www.haskell.org/ghcup/

Gif -> what purpose does it serve? I came here to install ghcup, I don't see how GIF is going to change anything.

I feel like I'm running around in circles a little bit. The point of all this was that other users complained they don't really know what ghcup is or does on their machine, when all they see is an instruction they are supposed to copy into their terminal, see here: tomjaguarpaw/tilapia#92

I'm going to accept that I won't satisfy all users. And I'm confident that showing more information is necessary.

Stack has a good start actually, better than ghcup I would say -> they quickly say what Stack is and then tell you how to install it.

Ok, now ghcup has too little info? I feel your points are contradictory: you want the old page back that had zero information on what ghcup is or does, but find the stack homepage more informative. You can't have both.

I am sorry that this discussion went in the direction where you feel the need to be defensive -> I meant to provide constructive feedback, not to cause distress, and I value all the work you are all doing!

I opened this issue to give a data point, which is my experience on the potential newcomer journey. While I did also offer some solutions, I didn't demand that anything be done about it. Instead, I wanted this to be potentially useful information that others (like you), more experienced with this area, will take as a possibly useful perspective, with a grain of salt.

I am looking above at my comments so far and I can't find where I demanded or even suggested changes to ghcup home page. I did describe my journey, and I even suggested some solutions, but those were aimed at potentially creating new page, haskell.org/getting-started, and not modifying the ghcup page. And I never demanded any changes be made.

I didn't plan to get into discussion about ghcup home page further than my initial feedback -> you started discussing it so I continued onto that.

As for "ease of usage" vs "amount of information" -> this is why I provided initial context when I opened this issue, explaining my background and from which perspective I am approaching this. The name of the very issue is "Optimizing initial experience on haskell.org for the first-time Haskell user" -> but you are saying now that is not what you think is important. That is fair, but then I am not sure why go into the length of discussing all this with me only to tell me you don't think it is important, if I opened an issue about specifically that.

[hasufell]

I opened this issue to give a data point, which is my experience on the potential newcomer journey.

Sure. We don't really have to agree to have a discussion.

I think it would be worthwhile to get feedback from actual newcomers. This could be done in universities (at the end of a course or so) or through the haskell survey (although I doubt many newcomers will be part of that survey).

Pretending to be a newcomer is hard.

The name of the very issue is "Optimizing initial experience on haskell.org for the first-time Haskell user" -> but you are saying now that is not what you think is important.

No, I didn't say that. I actually proposed to ditch the entire download page and just redirect to ghcup. That would mean there's one page less to visit/understand. But that idea was abandoned for political reasons, so we're stuck with it.

---

This is what I think are the relevant 3 "use cases" that need to be satisfied:

1. Get general information about the language and play with it online: I think haskell.org somewhat satisfies this, the landing page is pretty clean and has an interactive introduction. Having a dedicated playground would be a plus, but isn't needed.
2. Install the toolchain: I consider this problem solved. The remaining hoops (indirection through the downloads page) are minor.
3. Start reading a tutorial or course about the language: we don't have something concise or "community agreed upon" here. https://www.haskell.org/documentation/ gives a lot of links, but a newcomer won't know which one to pick. It's the devil of choice.

That's why I think the only real problem left is 3.

[tomjaguarpaw]

Thanks again for this. Here is a very brief summary of what I think needs tackling. I'm not sure over what timescale we'll have the resources to tackle this though, roughly in order of importance.

• Make it much clearer how to get started on the front page

  e.g. big orange "get Haskell" or "get started" button

• Streamline the downloads page

• Decide what should be done with the Haskell Platform page.

  Has it been superseded by the downloads page? If so then should we remove it? Seems misleading to keep it around. (But make sure the downloads page is a high enough quality replacement -- see above)

• Either add a "getting started" page or migrate the downloads page to become a "getting started" page.

• Do we make it clear enough that the stack team recommends that stack should be installed separately from ghcup?

  (It seems pretty clear already, but since the issue was raised we should probably give it some thought.)

[Martinsos]

@tomjaguarpaw sounds great, I believe this would cover everything based on my feedback!

I actually didn't realize that stack team recommends that stack should be installed separately from ghcup. I understood haskell.org recommends stack be installed separately, but when I saw that ghcup can also install stack, I thought the reason why haskell.org recommended to install stack separately might be that haskell.org docs are somewhat older and that at the point in time when they were last updated ghcup didn't yet support stack.

Even now when I understand that stack team recommends installing it on its own, I am still not sure which approach to use, since I conclude that if ghcup offers a way to install stack, they certainly think it is good enough, they wouldn't be offering it otherwise. So whom do I trust? I would probably try to go with ghcup just to keep things simple and if I encounter problems I would look into installing stack as a standalone thing.

[jneira]

alternatively it would be great to report any stack related problem when installed with ghcup in the ghcup repo itself, to help improve support for it
maybe when the ghcup support has been tested enough time we could try again to simplify installing instructions