Adding a Getting Started page #214
Conversation
|
I just realized #208 is trying to solve the same problem! I wasn't aware of it. It seems I did quite some more work here though, and I don't see at first glance anything in the other PR that is missing here. I also checked the discussion there, and I think this PR mostly aligns with the solutions reached there (except for link to Documentation, which wasn't resolved anyway). Although I did more changes so there might be some other points to discuss (like button on home page). Would it make sense to continue here then and close the other PR? |
There was a problem hiding this comment.
I'm not a committee member, my opinion has no weight here.
Thank you for trying to improve this part of the Haskell website. I think there's a lot of good information here, but I have a few comments on style. Note that I'm not a native English speaker either.
- Personally, I'm not a fan of cutesy writing style. I think the getting started page should be more straightforward and cut to the chase without trying to sell anything.
- I think this is a bit overly verbose. Ideally this should be kept to a 1 minute reading imo. This should be "this is how to install a haskell toolchain (or use the playground), this is how to setup an editor with haskell support, this is where you can find haskell tutorials, and there are popular communities" and that's it.
Verboseness was a common complaint against the download page in the past, I think the getting started page should be concise as well. - There are a few syntactic usages that throw me off a bit, for example using
->instead of:, or using(a, b, ...)instead offor example, a, and b., but I'm not an editor. - Having two getting started proposals is going to make this more difficult to whoever needs to approve this, why not collaborate?
site/get-started.markdown
Outdated
| isGettingStarted: true | ||
| --- | ||
|
|
||
| # Get started |
There was a problem hiding this comment.
I think this should either be an tiny page that fits on one screen or two screens (my preference), or it should include a TOC.
There was a problem hiding this comment.
Addressed in the big comment.
Super short: I don't think length is relevant as long as content is relevant. TOC is nice idea.
site/get-started.markdown
Outdated
|
|
||
| The most straightforward option is to go with **Visual Studio Code** - just install [Haskell extension](https://marketplace.visualstudio.com/items?itemName=haskell.haskell) and you are all set, it should work out of the box and use your installation of HLS. | ||
|
|
||
| Of other editors that have good Haskell extensions, the most popular ones are Vim and Emacs. |
There was a problem hiding this comment.
I think this is redundant unless the we link to the editor integration plugins/methods - I think users of vim and emacs like to tweak with their editor and will likely try to find information on haskell editor integration with their editor of choice on their own.
There was a problem hiding this comment.
I thought it a bit unusual to mention only one editor, when there are multiple out there that have good support for Haskell. Of those, I am pretty sure that vscode, vim and emacs make the majority of usage.
I am emacs user, my brother is vim, and I thought that seeing emacs/vim mentioned here, it would encourage me to know that others are also using emacs in haskell community.
Tha said, I am not strongly opinionated about this, we can remove this line if needed.
There was a problem hiding this comment.
This is the getting started page, either you help me get started or you're just teasing :)
There was a problem hiding this comment.
I don't understand why wouldn't I be helping / how am I teasing if I mention vim and emacs? VSCode, vim and emacs are three most popular editors for Haskell, with good support all of them.
We highlight VSCode because it is the easiest to get started with, it is very popular, and setup is super easy. People who have VSCode already or don't use vim/emacs will follow this happily.
We mention vim and emacs shortly. If you are vim or emacs user, you will be happy to see this, and will investigate further. If you are not vim or emacs user, you will ignore this.
If needed I can remove this line, this is not something I care that much about to compromise the PR for it, but it feels a bit biased to me to mention only vscode.
There was a problem hiding this comment.
I don't understand why wouldn't I be helping / how am I teasing if I mention vim and emacs?
What I'm trying to say is that emacs users are going to look for Haskell integration with emacs regardless to whether we list it here or not, because as an emacs user I do all of my programming in emacs regardless of the language. So I find it redundant, unless we help them get started. One way to help is to point to the relevant headings in the hls configuration docs.
What I'm trying to say is that the getting started page should not send anyone to google anything. If it's mentioned here, it should include enough context, or include the relevant links to more information. So either we don't write "emacs integration is available" and count on emacs users to google anyway (because they likely will), or we save them the search and send them to the relevant links.
There was a problem hiding this comment.
Sounds good @soupi , what I did now is removed the paragraph that mentions emacs and vim and replaced it with
To learn about support for other editors, check out [HLS docs for editor configuration](https://haskell-language-server.readthedocs.io/en/latest/configuration.html#configuring-your-editor).
Finally, if that still doesn't feel right, I can also remove that, but I think it now follows your recommendation from above.
site/get-started.markdown
Outdated
|
|
||
| Of other editors that have good Haskell extensions, the most popular ones are Vim and Emacs. | ||
|
|
||
| ## Running first lines of code |
There was a problem hiding this comment.
I think this section could instead be a link to an existing tutorial, or be reduced to "let's check that we can compile a program with the tools we installed, for me information about the core tools see this tutorial".
There was a problem hiding this comment.
Addressed in the big comment!
Super short: I believe this section is valuable as it gives users a quick win with Haskell and wraps together this whole getting-started guide.
site/get-started.markdown
Outdated
| - [r/haskell](https://www.reddit.com/r/haskell/) | ||
| - [Haskell Discourse](https://discourse.haskell.org/) | ||
| - [https://wiki.haskell.org/IRC_channel](https://wiki.haskell.org/IRC_channel) |
There was a problem hiding this comment.
A short description of each might be in order? I would even replace them with a link to the Haskell Planetarium.
There was a problem hiding this comment.
Haskell Planetarium is cool, but it has so many links on it, too many for getting started I think. ALso, is it an official resource? What is wrong with us listing the 3 most popular places here where Haskellers are?
I didn't want to get into descriptions because I felt it is hard to write something without putting one option above the other and therefore getting subjective. Do you have any suggestions on what those descriptions could be?
There was a problem hiding this comment.
Having a few links seems like a good idea. Too many options would just be confusing for people.
site/index.html
Outdated
| <div class="span12 col-sm-12" style="padding-top: 10px;"> | ||
| <br/> | ||
| <p class="text-center"> | ||
| <a href="/get-started/" class="btn btn-lg btn-primary" style="font-size: 1.5em">GET STARTED</a> |
There was a problem hiding this comment.
| <a href="/get-started/" class="btn btn-lg btn-primary" style="font-size: 1.5em">GET STARTED</a> | |
| <a href="/get-started/" class="btn btn-lg btn-primary" style="font-size: 1.5em">Get Started</a> |
I would use the same color as the purple background in the section below it, and I think the Haskell logo is now not aligned with the right side, but I'm not expert in this.
There was a problem hiding this comment.
Before it was aligned regarding the top border, now it is aligned vertically, due to the space that the button occupies, so it looked weird when aligned by the top border. That said, I am no designer so I can't tell if this is the best way to do it!
There was a problem hiding this comment.
@soupi thanks for such a detailed review!
I will write a bit bigger comment here, to address multiple of your comments since some of them overlap.
-
Cutesy style and selling:
Got it, I personally love to make content a bit fun and light when possible, but I understand that preferences here are subjective. Since Haskell is often perceived as academic and hard I thought it might be a nice change of pace, showing that Haskell is friendly and approachable! Let's see what others say, I am ok with toning it down if needed.
Oh and selling -> What do you mean by that, do you mean the excited tone? I get that it is a bit informal, but since people reading this are evaluating how much of a chance should they give Haskell, I thought it makes sense to try to make it exciting. -
Length of getting-started page and content that should go onto it:
I think of "getting started" page as a first glance into Haskell, that prepares you for further steps. You heard about Haskell, you want to give it a quick try, so you come to Haskell webpage, you see the official getting started guide, and you go for it. Therefore we help you set things up, get a taste of Haskell by writing a bit of code, help you join a community, and point you to resources for further learning. At this point, you haven't spent much time but you have already experienced many parts of Haskell and had the first couple of wins (set it up, joined the community, ran the first program).
This means more content than quickly pointing them to external links, that is true (although we do quite some of that also). But I think it is important that this first experience they have is somewhat guided, that it keeps them involved a bit and handholds them. Check out https://www.rust-lang.org/learn/get-started -> they are also not shy on content and make sure to take you through the basic things before sending you off.
You mention in other comment that you would kick out the part with writing the first program. I would argue that instead, it is important that we help them write the first lines of Haskell, since there is no official book or tutorial for Haskell, and this way we give them an easy quick win. Picking up a book / tutorial and is a big step, much harder than following couple of lines of code from "getting started" guide. Finally, rust-lang get-started page I linked above also has running the first program, if that means something. I am up for providing better code examples though if you have some ideas!
That said, I do agree it makes sense to keep it as short as possible, but is it important that it has a specific length (you mentioned 2 screens)? I don't think it matters much, as long as the content is easy to consume, divided into clear steps, and relevant. But I am happy to see if we can kick some parts out that might not be relevant! -
Me using arrows and (...) instead of "and":
True I sometimes go overboard with arrows and similar non-standard syntax, I am happy to fix any weirdness based on suggestions! -
Two proposals:
Yes we should collaborate! @lsmor would you be up for taking a look at this PR? I took a look at yours and I believe this one is following the same direction as yours but is then building more upon it. The only thing this PR doesn't have is the Gitpod part, because I thought that is a bit too much off-topic. -
TOC might be a nice idea!
I wrote a bit long comment, here is summary:
- I don't think we should worry about the length, as long as the content is relevant and we are doing our best to be succinct.
- I think having a section in "getting started" with writing the first program is important, to give them a quick win with Haskell.
- Adding TOC might be interesting!
- I am open to changing style, both writing and tone, per suggestions, if others also think it should be changed.
site/get-started.markdown
Outdated
| isGettingStarted: true | ||
| --- | ||
|
|
||
| # Get started |
There was a problem hiding this comment.
Addressed in the big comment.
Super short: I don't think length is relevant as long as content is relevant. TOC is nice idea.
site/get-started.markdown
Outdated
|
|
||
| The most straightforward option is to go with **Visual Studio Code** - just install [Haskell extension](https://marketplace.visualstudio.com/items?itemName=haskell.haskell) and you are all set, it should work out of the box and use your installation of HLS. | ||
|
|
||
| Of other editors that have good Haskell extensions, the most popular ones are Vim and Emacs. |
There was a problem hiding this comment.
I thought it a bit unusual to mention only one editor, when there are multiple out there that have good support for Haskell. Of those, I am pretty sure that vscode, vim and emacs make the majority of usage.
I am emacs user, my brother is vim, and I thought that seeing emacs/vim mentioned here, it would encourage me to know that others are also using emacs in haskell community.
Tha said, I am not strongly opinionated about this, we can remove this line if needed.
site/get-started.markdown
Outdated
|
|
||
| Of other editors that have good Haskell extensions, the most popular ones are Vim and Emacs. | ||
|
|
||
| ## Running first lines of code |
There was a problem hiding this comment.
Addressed in the big comment!
Super short: I believe this section is valuable as it gives users a quick win with Haskell and wraps together this whole getting-started guide.
site/get-started.markdown
Outdated
| - [r/haskell](https://www.reddit.com/r/haskell/) | ||
| - [Haskell Discourse](https://discourse.haskell.org/) | ||
| - [https://wiki.haskell.org/IRC_channel](https://wiki.haskell.org/IRC_channel) |
There was a problem hiding this comment.
Haskell Planetarium is cool, but it has so many links on it, too many for getting started I think. ALso, is it an official resource? What is wrong with us listing the 3 most popular places here where Haskellers are?
I didn't want to get into descriptions because I felt it is hard to write something without putting one option above the other and therefore getting subjective. Do you have any suggestions on what those descriptions could be?
site/index.html
Outdated
| <div class="span12 col-sm-12" style="padding-top: 10px;"> | ||
| <br/> | ||
| <p class="text-center"> | ||
| <a href="/get-started/" class="btn btn-lg btn-primary" style="font-size: 1.5em">GET STARTED</a> |
There was a problem hiding this comment.
Before it was aligned regarding the top border, now it is aligned vertically, due to the space that the button occupies, so it looked weird when aligned by the top border. That said, I am no designer so I can't tell if this is the best way to do it!
|
Again, I'm not a committee member, my opinion has no bearing on whether this proposal will be accepted or not, I'm commenting my opinion because you've tagged my specifically :)
A lot of words, basically - this is my opinion - I think a reader will expect the get started page to "just get to the thing". But again, my opinion :) |
|
Hi! Author of the other PR here. I am happy to close mine and collaborate within this one (which is indeed more elaborated). I will take a deeper look after, but the first screenshot doesn't look like a minimal, clear and strightforward guide to me. In #207 I exposed what do I mean by minimal, clear and strightforward guide. Notice that I am not saying It is wrong, but in my experience, newcommers just want a step by step guide with at most one action by step and absolutely nothing else. Try to not waste words describing what ghcup is or the For the sake of example, below there is a capture of how my PR looks like. Of course, it doesn't mean that it should be the best way of doing things but I'd argue the following good points.
For completeness, I think my PR missed:
From what I've seen. Many, many, many developers aren't that familiar with terms like "language server protocol", "interpreter" or "compiler". I know it sound crazy but there is a huge amount of developers who just installed vscode for javascript programming or pycharm for python, and these editors are pretty much preconfigured with good sensible defaults. For them the python interpreter is just python. For example, I've seen people not understanding the difference between cpython and pypy (two different python interpreters), or not knowing what I don't want to sound elitist, but just to warn you about the high amount of people which aren't used to read documentation or configuring an environment. I think Haskell community is in general not warned about this. Hope it helps!! |
There was a problem hiding this comment.
@soupi and @lsmor thanks for the detailed feedback!
I know none of you are committee members, but I would love us to shape this PR together so that both of you feel good about it, since it is obvious that you care a lot about providing the best experience for new Haskellers, and I think the PR will have a much better chance if more of us are approving of it and stand behind it. Also, if we can all agree on it despite different perspectives, that gives it a better chance to be acceptable to a broader set of new Haskellers.
@lsmor -> thanks for sharing the MCS concept with me, I wasn't aware of that issue before! I certainly agree on straightforward and clear. "minimal" -> I mostly agree, but I think it depends on what we want to deliver. If it is just a bunch of links to read in given order, then minimal can be very minimal indeed. If it is instead a bit of hand holding to successfully do a first couple of steps in Haskell journey, with the end result of having some basic understanding of what you need for Haskell development and what to do next, and leaving with a nice "win", then I think minimal can be a bit longer.
Since you both suggested making the guide shorter / less verbose, I did a new iteration where I removed quite a few things.
I also added TOC, since you @soupi suggested it and @lsmor you also said it would help to anticipate the number of steps, which is what you had in your PR but was missing in this one.
@lsmori, regarding creating a new project with cabal, the reason I skipped that is because:
- It is not necessary to get started with Haskell.
- Previous PRs/issues that have been trying to do similar things as we here have failed to get merged due to not being able to get the buy in from all the parties on which build tool should be recommended. That is why I thought it would be best to not get into that at all, to make sure this guide gets merged, since I think there is a lot of value in it even if we don't recommend a specific build tool or show how to use it (books / tutorials will have to do for that).
Your remark regarding devs not being familiar with some of those more complex terms -> not crazy at all, I agree that is the case. That is why I think this Getting Starting guide is so important, because it lays forward clear path on getting started with Haskell without needing to make decisions that you are just not equipped to make. Instead, it is clear what is recommended and that is it. And that is what I think Haskell community often fails at -> giving a straightforward answer.
The only thing missing is recommendation of cabal vs stack, but as I mentioned, I don't think that is something we want to tackle right now, so as to not reduce the chances of the PR getting merged.
Ok, I did changes that I hope get PR closer to what you both feel is right direction, pls check them out and let me know how you like it now! I will be away the rest of this week but next week I am back as usual.
site/get-started.markdown
Outdated
| > ghc --version | ||
| > haskell-language-server-wrapper --version | ||
| > cabal --version # If you installed cabal | ||
| > stack --version # If you installed Stack | ||
| ``` |
There was a problem hiding this comment.
I also removed this, I believe GHCup already gives enough feedback upon successful installation of tools.
site/get-started.markdown
Outdated
| ``` | ||
|
|
||
| ### Editor | ||
| HLS (Haskell Language Server), which you just installed via GHCup, is the one that brings all the cool IDE features to editors, so as long as your editor has a decent Haskell language extension that utilizes HLS, you are good. |
There was a problem hiding this comment.
I also removed this, for the sake of brevity.
site/get-started.markdown
Outdated
|
|
||
| The most straightforward option is to go with **Visual Studio Code** - just install [Haskell extension](https://marketplace.visualstudio.com/items?itemName=haskell.haskell) and you are all set, it should work out of the box and use your installation of HLS. | ||
|
|
||
| Of other editors that have good Haskell extensions, the most popular ones are Vim and Emacs. |
There was a problem hiding this comment.
I don't understand why wouldn't I be helping / how am I teasing if I mention vim and emacs? VSCode, vim and emacs are three most popular editors for Haskell, with good support all of them.
We highlight VSCode because it is the easiest to get started with, it is very popular, and setup is super easy. People who have VSCode already or don't use vim/emacs will follow this happily.
We mention vim and emacs shortly. If you are vim or emacs user, you will be happy to see this, and will investigate further. If you are not vim or emacs user, you will ignore this.
If needed I can remove this line, this is not something I care that much about to compromise the PR for it, but it feels a bit biased to me to mention only vscode.
|
I think this look much better! Thanks for being receptive to feedback. Regarding |
site/get-started.markdown
Outdated
| ```hs | ||
| main = do | ||
| putStrLn "Hello, everybody!" | ||
| putStrLn ("Please look at my favorite odd numbers: " ++ filter odd [10..20]) |
There was a problem hiding this comment.
Wait, this doesn't look like it will compile, filter odd [10..20] isn't of type String. perhaps add a let and show?
There was a problem hiding this comment.
Ouf, fixed. thanks!
|
There are large parts of this PR that overlap or duplicate what's already on the GHCup page. E.g. https://www.haskell.org/ghcup/steps/ Of course the GHCup homepage is maintained by myself (so far without committee involvement), so that isn't an argument against this PR. But it's something to discuss. |
site/get-started.markdown
Outdated
| 1. **GHC** -> Haskell compiler. We will use it below to run our examples, but in practice, you will mostly be using a build tool like `cabal` or `Stack` to build your code, instead of `GHC` directly. | ||
| 2. **HLS** -> Haskell Language Server -> You won't use this directly, instead your code editor will use it in the background to provide you with a great experience while editing Haskell code. | ||
| 3. **cabal** -> Haskell build tool -> You will use this to structure your Haskell projects, build them, run them, define dependencies, ... | ||
| 4. **Stack** -> Haskell build tool -> alternative to `cabal` |
There was a problem hiding this comment.
Notice that stack needs some special configuration to integrate with hls. Actually, ghcup warn you about this when installing stack. If newcommer skip the configuration step, hls will complain about "could not fin ghc" or something like that. I've already seen a few reddit/SO question about this, so maybe it worths to point this out.
The ghcup output looks like this:
[ Info ] verifying digest of: stack-2.9.1-linux-x86_64-static.tar.gz
[ Info ] Unpacking: stack-2.9.1-linux-x86_64-static.tar.gz to /home/<username>/.ghcup/tmp/ghcup-e994793785bef45f
[ Info ] Installing stack
[ Info ] Stack manages GHC versions internally by default. In order to make it use ghcup installed
[ ... ] GHC versions you can run the following commands:
[ ... ] stack config set install-ghc false --global
[ ... ] stack config set system-ghc true --global
[ ... ]
[ ... ] On windows, you may find the following config options useful too:
[ ... ] skip-msys, extra-path, extra-include-dirs, extra-lib-dirs
[ ... ]
[ ... ] Also check out: https://docs.haskellstack.org/en/stable/yaml_configuration
[ ... ]
[ ... ] !!! Additionally, you should upgrade stack only through ghcup and not use 'stack upgrade' !!!
[ ... ]
Success
Also, new stack version allows for instalation hooks, but I don't know it ghcup uses that by default yet (I think it is comming) @hasufell might help here.
There was a problem hiding this comment.
I could use some help with figuring out what we write about this. @hasufell , any immediate opinion on this?
site/get-started.markdown
Outdated
| - [Join the community](#join-the-community) | ||
| - [Next steps](#next-steps) | ||
|
|
||
| ## Set up Haskell dev environment |
There was a problem hiding this comment.
Under this header I'd add a little text like (with better phrasing as mine):
A complete haskell dev environment consist in the haskell tooling (compiler, language server client and build tool) and an editor compatible with the language server protocol. The quickest way to get all of those is:
- Use Ghcup to manage all haskell tooling
- Use vscode as your editor with the haskell extension.
I think it is important to anticipate how many things are involved, otherwise it isn't clear how much of the guide should I read.
Let me know what you think
There was a problem hiding this comment.
Sure, sounds good, added it!
Indeed. Isn't this fact a proof that something is wrong with haskell.org? I mean, clearly the place this info should exists is within the haskell's oficial page, not within ghcup, which is a tooling manager... (Not trying to underrate your work in the |
Yes. That guide was originally a PR to haskell.org, but the author got annoyed by the inaction and lack of feedback and withdrew the PR: #88 |
|
Thanks very much to @Martinsos for this, and to @lsmor too for his version. Thanks too to the reviewers here. We're still some way off being able to merge something like this, as I expand on below, but I just wanted to leave some observations:
The reason that we're still a way off being able to merge something like this is that we still haven't established consensus that GHCup should be recommended as the installer for Stack, as well as the other tools. The good news is that I think we are very close! I just see a couple of minor things to be dealt with. There is another GitHub issue tracking this. Once that's resolved we are free to recommend GHCup as the single installation tool and improve the onboarding instructions to benefit from that! |
|
I'm not sure what this question means.
GHC, Cabal and HLS.
Completing the outstanding tasks on #212 achieves consensus, as far as I am aware, based on discussions, both public and private, with members of the Stack leadership. |
That sounds like a good thing, doesn't it? In the sense that this PR then contains information that you also agree is valuable? Is there something particular you would like to discuss? I am aware of you previous attempt to do something very similar with #93 , so I would assume you would be in support of the change proposed by this PR? |
Thanks for taking a look @tomjaguarpaw ! I got a lot of good feedback from @lsmor and @soupi , and I applied most of it -> I believe we took care of all the major points, and most of the minor ones. I will let them confirm that, but we shortened get started page, made sure it doesn't digress too much, removed the "cutesy" tone I started with, added TOC so it is clear what awaits the reader, and kicked out some redundant parts. I also updated the images at the start of this PR, so now they reflect the latest version of the PR, so you don't have to run it yourself. I see two ways to proceed:
Choosing between (1) and (2) depends on estimating how long it will take for (1) to happen vs how much effort would it take to go with (2). I am a bit lacking in knowledge to make any of these estimates properly, so I could use some help here! If we go with (2), what could that look like? |
|
@mpilgrem, maybe this PR would also be interesting to you, to comment on? |
|
@Martinsos, thank you for thinking of me. I don't think I can add much - I am not a teacher or a web site designer. 9 years ago, I was a 47-year old total 'newcomer' to Haskell (via Apple Basic, 6502 machine code, C, Fortran 77, Excel, C# and Lua), with a childhood interest in 'computing', a degree in theoretical physics, a career in financial consultancy, and access to Windows machines (only) at home and work and an iPad (hence Lua - Codea). I mention my path to Haskell only to state the obvious: one 'newcomer' can be very different to another. To design the page, I think you need to have a clear idea in your own mind: what does the newcomer already know (including vocabulary), and what needs to be explained? For example, my half-joke/half-truth is everything I know about Linux has been learned trying to get Haskell to work on Windows. I mention assumed vocabulary above because unfamiliar terms can be a barrier. Anything the newcomer is assumed not to know already, but needs to know, needs to be introduced (even if only 'lightly'). A challenge would be to get a newcomer to create an executable (an 'app'?) with Haskell without encountering any unexplained 'technical' terms (once explained, a term can be used). Stack's own home page does not yet achieve that, but I am working on it. Looking at your introduction in the screen shot above, I would put the 'natural language' context to a button that says 'Get GHCup Here!' like this:
|
There was a problem hiding this comment.
Thanks for the effort here! Looks solid to me.
Now that the proposal to recommend installing Stack via GHCup has passed, seems like we can get this merged too. I'll ping other members of the committee about it to get things rolling again.
site/css/hl.css
Outdated
|
|
||
| /* Boostrap-style callouts (nice informational boxes), | ||
| taken from https://codepen.io/chrisdpratt/pen/QWBqKY . | ||
| */ |
There was a problem hiding this comment.
Love the comment here—answered the exact question I had on seeing the CSS classes :)
site/get-started.markdown
Outdated
| - [r/haskell](https://www.reddit.com/r/haskell/) | ||
| - [Haskell Discourse](https://discourse.haskell.org/) | ||
| - [https://wiki.haskell.org/IRC_channel](https://wiki.haskell.org/IRC_channel) |
There was a problem hiding this comment.
Having a few links seems like a good idea. Too many options would just be confusing for people.
site/downloads.markdown
Outdated
| ### Via native OS package manager | ||
|
|
||
| Alternatively, many operating systems provide GHC, cabal and Stack through their native package manager. The packages are often out-of-date but if you prefer to use this method of installation then you will find useful links below. | ||
| Alternatively, many operating systems provide GHC, cabal and Stack through their native package manager. The packages are often out-of-date and we don't recommend this method of installation, but if you prefer to use this method then you will find useful links below. | ||
|
|
There was a problem hiding this comment.
Can you please drop this part? The current wording is part of a compromise to satisfy a segment of the community which insists that operating system packages are the one true way to install Haskell (or anything). The current wording is literally true: they are often out-of-date. The proposed wording suggests that the Haskell.org committee has made a value judgement about what is or is not to be recommended. I would prefer to avoid that. Rather the relative order in which we present the various options should implicitly convey that information.
tomjaguarpaw
force-pushed
the
getting-started
branch
from
aa2a5da to
ea00662
Compare
|
I rebased this on latest |
tomjaguarpaw
force-pushed
the
getting-started
branch
from
ea00662 to
b266b4e
Compare
|
Hmm, perhaps I wasn't being as clever as I thought, since I then pushed the wrong thing and it closed the PR :( @Martinsos, would you mind pushing the following to your branch and then reopening the PR? https://github.com/tomjaguarpaw/www.haskell.org/tree/getting-started Sorry about that. |
|
Anyway, what all this juggling is in aid of is the following: When a PR contains some elements that are obvious quick wins and some elements that are more debatable the obvious quick wins get held up unnecessarily by bike shedding. The Big Friendly Button is an obvious quick win. Let's get that in ASAP. I put up a PR. Then we can debate, at our leisure, the appearance of arrows and suchlike. |
|
@tomjaguarpaw I didn't completely get what happened here :D, but I reopened it as #227 , I believe we can continue from there! |
As a result of the discussion I started on HF Slack, I created this PR to improve UX of haskell.org for the new Haskellers, that want to get started with Haskell.
The problem I am trying to solve is described in details in the discussion I linked above, so I won't repeat it all here but will try to put it shortly:
I believe that currently haskell.org is relatively unfriendly for the newcomers, mostly due to the unclear steps for getting started + somewhat confusing UX.
I believe we can fix this easily by copying what many other languages / webpages do, which is providing a "Getting started" page that takes beginners through setting up their dev environment, doing first steps in Haskell, pointing them to the communities they should join, and finally pointing them to the learning resources to continue with. While doing all this, it is important that path is clear and there are as little choices as possible.
I did the following main changes:
Some notes:
cabalinstead ofcabal-install(CLI) orCabal(lib) orcabal format(.cabal), because I believe it is too confusing to explain these differences to somebody who is taking a very first look at Haskell. In GHCup the term used is justcabal, and once they install it, they will call it withcabal, so for the start I think it is best to use just termcabaland later they will learn the difference.@tomjaguarpaw @soupi
EDIT (Oct 14th): updated photos to reflect new changes (fixes based on feedback from others).