Optimizing initial experience on haskell.org for the first-time Haskell user #136
Comments
|
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. |
|
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. |
|
Awesome @tomjaguarpaw , I am glad it helps! 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. |
|
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. |
https://www.haskell.org/ghcup/about/#why-should-i-let-ghcup-manage-stack
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).
ghcup installs haskell-language-server-wrapper, yes.
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
What is complex about it? Compare with stack and cabal: I'd argue GHCup homepage is much more friendly.
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.
Can't follow here.
Like this? https://www.haskell.org/ghcup/install/#supported-tools
Like this? https://imgur.com/1CHtfnm.png
Yeah sure, could do that too, but we don't have a definite community agreed upon tutorial.
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.
Sounds like #88 which was abandoned due to lack of approval/review by the haskell.org committee. |
|
https://gitlab.haskell.org/haskell/ghcup-hs/-/merge_requests/201 Edit: updated page is live https://www.haskell.org/ghcup/ |
|
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.
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.
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?
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.
By third party I mean that it is not an official tool. Kind of like pacman is official package manager for archlinux, but
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. 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.
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).
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.
Explained above.
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.
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.
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.
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 .
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. |
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.
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.
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
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.
Totally disagree with you. The homepage is directed towards users, just like stack and cabal. I'll link to those pages again: 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/
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.
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. |
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 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. |
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.
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:
That's why I think the only real problem left is 3. |
|
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.
|
|
@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. |
|
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 |
They aren't old as you can see from the PRs in this repository.
Well, I don't know if it's the "stack team". It was Chris Dornan, who suggested that ghcup is unsuitable for this task, after he suggested it should be added to ghcup. So I'm as confused as you are. The main concern was that stack by default doesn't really pick up ghcup installed GHC versions and you end up with "duplication". I've provided a PR for that, which has seen no comments from stack developers until now: commercialhaskell/stack#5585 Another issue is that
I don't think there's lack of information on this issue. |
I agree there is no lack of information on this issue if you take enough time to research and find all it. But if you are installing Haskell for the first time and reading instructions at haskell.org, you will most likely not end up checking out when the PR to update those same instructions was last made. Those instructions printed by ghcup are certainly great, they do provide needed information at the right moment. |
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
ghcupandstack.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:
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.
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.
The text was updated successfully, but these errors were encountered: