Redo the entire download page, fixes #12

[hasufell]

@mattbaumann @gbaz @emilypi

---

Pictures:

[jneira]

The page looks really great, congrats
A minor nitpick, building from source is an option that is available for all os's and no only for linux. Maybe it is more difficult in osx and windows but possible 🙂
Other change that could be debatable is the different handling of stack 😉

[hasufell]

A minor nitpick, building from source is an option that is available for all os's and no only for linux.

Good catch.

Other change that could be debatable is the different handling of stack

Yes, this has been discussed previously.

To re-iterate and expand:

1. Stack is an advanced tool like nix that can be used with haskell. Albeit its popularity, it's more than just an installer and requires its own whole introduction, documentation, etc etc. E.g. installing stack and typing ghc or ghci doesn't work. People will have to study how it works. It's a fine addition to the Haskell toolchain, but doesn't need to be considered intrinsic part of it.
2. It's impossible to explain all options in-depth on a download page that is supposed to give beginners a concise and swift overview.
3. Including stack in the list of "Haskell toolchain" would force us to describe what it is, its differences to cabal, that it automatically installs GHC etc., further confusing users who want to make a choice and get started quickly. I don't see a way to maintain the current clean document structure when explaining stack in more detail.

[emilypi]

Stack is an advanced tool like nix that can be used with haskell. Albeit its popularity, it's more than just an installer and requires its own whole introduction, documentation, etc etc. E.g. installing stack and typing ghc or ghci doesn't work. People will have to study how it works. It's a fine addition to the Haskell toolchain, but doesn't need to be considered intrinsic part of it.

This statement is contradictory to your listing of cabal-install on the downloads list. The same arguments could be applied to cabal-install.

Including stack in the list of "Haskell toolchain" would force us to describe what it is, its differences to cabal, that it automatically installs GHC etc.

Did you mean to say Cabal is part of the toolchain for GHC? I would agree there, but cabal-install is separate nix-style tooling like Stack, with bespoke requirements. The statement that it is somehow fundamental (by virtue of being listed on the page) is inconsistent, and bound to infuriate people due to its incorrectness. You don't have to go into details regarding what either are. Just a small blurb would do, like "Stack is a build tool that automates GHC management and hooks into the Stable Hackage (Stackage) curation layer for its build plans", and then provide a pointer to the stack docs for more info. The same could be done for cabal-install, with the differentiator being that it plugs into raw Hackage by default.

I like your redesign - don't get me wrong. I think it could be less incendiary and be even more valuable with the above information and corrections.

[hasufell]

This statement is contradictory to your listing of cabal-install on the downloads list. The same arguments could be applied to cabal-install.

I don't think so. cabal-install is much smaller in scope than stack. It doesn't install ghc, it doesn't have resolvers, it doesn't have docker, nix, hpack integration, etc. etc.

Did you mean to say Cabal is part of the toolchain for GHC?

No, the term coined here was "Haskell toolchain". And I defined cabal-install as being part of that.

The statement that it is somehow fundamental (by virtue of being listed on the page) is inconsistent, and bound to infuriate people due to its incorrectness.

I think "Haskell toolchain" is quite an arbitrary term (similar to Haskell platform), I agree with that. It has little to do with GHC or boot packages. My understanding was that this download page is primarily visited by users, who are new to haskell and need the easiest solution forward, without getting bombed by all the different tools. As such, the definition of Haskell toolchain is simply a choice to accommodate the expectations of new users. Advanced tools are listed at the end of the page.

Just a small blurb would do, like "Stack is a build tool that automates GHC management and hooks into the Stable Hackage (Stackage) curation layer for its build plans", and then provide a pointer to the stack docs for more info. The same could be done for cabal-install, with the differentiator being that it plugs into raw Hackage by default.

I didn't describe cabal-install in detail either. The linked documentation describes what it is in detail. And the download page also links to the stack page, which describes it. Why would we duplicate that information? It'll raise more questions that will be unanswered, unless the user takes time to study the tool, which they should anyway.

The goal of this PR is to cause minimal confusion to new users trying to install and use GHC. Once we explain stack, we have to explain cabal-install in more detail as well and then explain that they're different approaches, have different overlapping scopes etc. Users are best advised to read the respective documentation. I don't believe in duplication of information, which is why I already don't like the linux distribution section too much.

[gbaz]

Since the platform now redirects people to chocolatey or ghcup I support switching the downloads page to point to those resources directly.

[emilypi]

it doesn't have resolvers, it doesn't have docker, nix, hpack integration, etc. etc.

It has solvers (i don't see the difference here), and it certainly has nix integration see here. It also recognizes darcs and git repositories in many of its commands, and requires Hackage to operate, which is additional infrastructure to learn. The point here in my coming back at you about this is that people will split these hairs, and the line being drawn seems arbitrary in that context. If you're going to make a change like this, be prepared for fire and fury, because it's going to piss of tool maintainers who believe that "simple" means other things.

No, the term coined here was "Haskell toolchain". And I defined cabal-install as being part of that.

There will be people who disagree with cabal-install being a part of that toolchain. It's a fact that most people in Haskell use stack currently per the state of Haskell yearly surveys, so this will cause further confusion in that context as well.

without getting bombed by all the different tools.

If this were the expressed goal, I'd agree, but here's where I think we get off track:

• cabal-install requires Hackage, ghc-up (or worse: manual GHC management), and Cabal.
• stack requires Stackage and hpack, manages GHC installs for you.

I am a cabal-install user, and I use it precisely for its finer-grained package management and because it's more complicated. I can tune more knobs to my exacting needs. But stack is the one i'd recommend to beginners, because it is a simpler environment at first interaction. The choice in deciding whether one of the other is more or less complicated is completely arbitrary. That is confusing.

And the download page also links to the stack page, which describes it.

At the bottom, next to Nix. Aside from that, the PR is out of order here, because it references stack instructions before it even mentions stack as an option. I say define stack as part of the tool chain and just put it up there in the first stanza with the rest of the fundamental haskell tools.

[hasufell]

But stack is the one i'd recommend to beginners, because it is a simpler environment at first interaction.

This is the opposite of my experience giving support on IRC and also my opposite professional experience when training haskell newcomers on the job. Of course that is anecdotal evidence from both sides.

There will be people who disagree with cabal-install being a part of that toolchain.

Sure, but I think we're talking past each other. This PR is not about overhauling the download page to be more detailed and well written.

This PR is a consequence of several years of inaction about the confusing state of the download section (see #12 ), which leads to frequent questions on IRC, reddit, etc. The choices made in this PR reflect my experience from those support sessions for newcomers.

There are two other approaches imo:

1. redirect people to stack for all supported platforms and leave cabal-install and friends as a footnote
2. make the download page explain all choices in more detail

My PR doesn't want to achieve either of those, because I think the problem is not the lack of detail, but newcomers getting dragged into decisions about competing tools, presented in a way that makes them unsure about what to pick.

[hasufell]

On the other hand: feel free to make use of this PR in whatever way. So if someone wants to add more stack-instructions etc., please go ahead. This is the second attempt at improving the download page and it doesn't have to be the last one.

[jkachmar]

tl;dr If this PR isn't meant to be an overhaul of the downloads page, I would prefer if we could reduce the scope to updating the style and only changing immediately relevant information.

If the door is being opened to a much more involved set of changes, I'd prefer if these changes could be made very deliberately so that the official landing page can be as representative as possible of the current state of Haskell tooling for new users.

---

Before anything else, I just want to start by saying thanks to @hasufell for putting in the time and effort of reworking the downloads page like this; everything seems concise and well-laid out.

Since I do some work with the Stackage team, though, I feel obligated to chime in a bit with respect to the discussion regarding stack above. Generally I agree with pretty much everything @emilypi's said so far, so I'll try to avoid retreading the same ground and limit my commentary to avoid adding too much noise to the discussion.

---

stack is an advanced tool like nix that can be used with Haskell [...]

This is definitely not the intent behind stack; I don't contribute to the CLI and can't speak for the project in any official capacity, my interpretation of stack's goals are that it should be no more complicated than cabal-install (ideally, less so, but it's fair to say that certain things are matter of taste).

Contrast this with nix, which has goals that are much wider in scope and therefore carries a lot more inherent complexity along with it.

The goal of this PR is to cause minimal confusion to new users trying to install and use GHC [...]

It's my perspective (which is likely a little biased based on my exposure) that Stackage has become a high-visibility part of the Haskell ecosystem, to the point where I would actually be concerned about potential new-user confusion resulting from not mentioning the tooling that's designed to cleanly interoperate with it.

I understand the concern associated with providing links and brief summaries to tools with overlapping concerns, but I'd like to suggest that the maintainers also consider what an official page like this conveys as an authoritative source of truth.

Sure, but I think we're talking past each other. This PR is not about overhauling the download page to be more detailed and well written.

I understand that this isn't the intent behind the PR, but as @jneira points out above it is a consequence of it based on how things have been reorganized.

If the goal here isn't to open a discussion around overhauling and streamlining the documentation for downloading/installing Haskell tooling, then perhaps it would be better to limit/change the scope of changes here and then open a new issue or PR focused on more substantial changes.

---

Overall I'm sympathetic to the desire that this page should be kept as simple as possible, however I really do think that the Haskell ecosystem hasn't "settled" to the point where we can reasonably provide an authoritative answer to what constitutes "the Haskell toolchain".

I'm not entirely sure what an acceptable solution looks like, but (as a very small example) I would suggest considering the following sort of language as an alternative to the introductory paragraph:

This page describes, and provides instructions for installing, common Haskell tooling:

• the Glasgow Haskell Compiler (GHC): the de-facto standard Haskell language compiler
• cabal-install: a command-line package management tool for downloading Haskell package dependencies, compiling packages, creating distributable packages, and uploading them to Hackage
• the Haskell Language Server (optional): a language server that provides information about Haskell programs to IDEs, editors, and other tools

The primary differences (aside from the liberties I've taken with the wording) is that this section no longer attempts to describe any one authoritative Haskell toolchain.

It also leaves room to add a second section immediately below mentioning stack and/or nix briefly and then defering to their documentation (e.g. by linking directly to https://docs.haskellstack.org/en/stable/README/).

---

P.S. I'm sorry this ended up being such a long comment; I'll absolutely try to keep future replies shorter, I just wanted to condense my responses down to the thread-so-far in one spot.

[ketzacoatl]

First, thank you to everyone in this discussion, and for the effort to make improvements to this page.

A few pieces of feedback, and my own two cents:

• I believe the downloads page should be as straight-forward, minimal, and inclusive as possible. Potentials decisions and their Options should be obvious. There should not be lots of reading and thinking and wondering.
• The page should aim to connect the user to the tools/downloads, and should not aim to explain the tools. The page should instead link to reasonable "getting started" documentation for each tool. When I read the page as a new / potential haskell user, I should be aware that there are different tools and I should have the ability to not only discover more information about those tools, but also to "have you tell me what to do".
• The page should make it obvious which tool is endorsed/recommended if you don't know what to do.
• Experienced users know how/where to discover more information or expand what they know. New users don't know what they don't know. New users need authoritative documentation that guides them through the initial phases of their experience with Haskell. The downloads page is not the place to explain the tools, but new users do need an authoritative guide and it should be clearly linked to / accessible from the downloads page.
• The authoritative guide ought to endorse a specific route to onboarding and getting started. Having a second/alternative route as well is fine, and that's the place to explain to the user what the decision is about and what their choices are.
• Given the circumstances, IMO changes like "removing stack from the downloads page" ought to go through more scrutiny, and have more evidence to support the change than what has been presented here.
• I'm just one person, but I have never found cabal-install easy or beginner-friendly in my experience. I was not able to effectively learn and use Haskell with cabal-install, and that did not change for me until Stack came around. After years of learning and struggling, I am able to hold my own and navigate most of my Haskell challenges (still get stuck on things I need help getting unstuck on), so I recently thought it would be interesting to give cabal-install another shot. It did not go well, and I could not even find value in sorting out my confusion over which subcommands did what and why I'd want one over another. I can see how you might want to use it as an advanced user, and I think it should be on the downloads page, but I would never recommend cabal-install to the generic new/potential user learning haskell, and I don't believe it should be endorsed as the blessed tool for onboarding.

Again, thank you for discussing improvements to this page, it's important work.

[hasufell]

@jkachmar

This is definitely not the intent behind stack;

That may be true. But just to name a few things that keep confusing newcomers:

• ghc, ghci etc don't work, where's my compiler?
• understanding the relationship between package.yaml and foo.cabal and that hpack just supports a subset of the Cabal file format
• understanding that stack build doesn't work in all projects, even if it's a single-package project
• understanding stack init and that it chooses a resolver, understanding what a resolver is and what stackage is (AND hackage, because stack makes use of that too)
• understanding what to do if a package is missing from stackage (and when to choose to upgrade to a newer snapshot in order to fix such issues)
• how to update compiler? Update snapshot? Use system GHC?
• understanding the pantry syntax (many ways to express the same thing)

To me, stack is clearly superior to cabal in terms of features. And that's because it follows a different philosophy and has more concepts you need to be aware of.

Another argument is that most languages do not have a tool like stack. cargo, pip, npm etc. all resemble the GHC+cabal toolchain more than they do resemble stack. So newcomers are more likely to be confused by it.

Whether that aligns with the project goals of stack is something relevant for the project maintainers, but not for making a choice about how to structure the download page.

It's my perspective (which is likely a little biased based on my exposure) that Stackage has become a high-visibility part of the Haskell ecosystem, to the point where I would actually be concerned about potential new-user confusion resulting from not mentioning the tooling that's designed to cleanly interoperate with it.

Stack is clearly mentioned. And stackage is indeed an integral part of developing haskell production software (wether it's via nix, cabal or stack). But I don't see why newcomers should be concerned with all these concepts. They aren't needed to get started. They're advanced.

I understand the concern associated with providing links and brief summaries to tools with overlapping concerns, but I'd like to suggest that the maintainers also consider what an official page like this conveys as an authoritative source of truth.

If the download page is about pleasing political parties interests in having their tools properly represented, then that motivation doesn't align with this PR, that is true.

I'd be similarly fine with the download page mentioning stack primarily and only having a footnote about cabal, ghcup etc. In that case, we can redirect newcomers to the stack support channels.

If the goal here isn't to open a discussion around overhauling and streamlining the documentation for downloading/installing Haskell tooling, then perhaps it would be better to limit/change the scope of changes here and then open a new issue or PR focused on more substantial changes.

The goal is having a discussion. Especially since not many have participated in it, which has stalled some of the effort to improve the download page.

It is just that my evaluation of the problem is this:

1. too many link redirections... some links point to haskell platform (which is fuzzy in scope these days), some links point to a linux subpage (under minimal installers) with all sorts of distro-specific instructions and no mention of ghcup, some point to stack, some to cabal
2. No help in aiding decisions... I just want to get started, what do I do?
3. Mentioning both stack and cabal, but making no effort in explaining why both are mentioned, what the differences are, what choice I should make
4. Being overloaded with choices

---

If you can come up with a way to achieve both goals, as in a) having a minimal download page that doesn't give users anxiety about making the right choice and b) having a proper representation and explanation of all existing tools and their differences, then go ahead. My opinion is that b) does not belong on the download page, but on the wiki.

[hasufell]

Ok, what about this: guiding the user through 3 choices:

1. picking cabal toolchain vs stack toolchain
   • explain that cabal+GHC is more traditional and stack more batteries-included, possibly linking to a more verbose wiki page explaining the details
   • explain that these aren't exclusive, but the user probably wants to go with just one for now
   • suggest a default if the user is unsure: e.g. pick cabal toolchain
2. Picking the platform: this should be straight-forward as above
3. Picking the installation method
   • present all methods (for stack that would be just one)
   • also make a clear recommendation

So if the user is unsure, they can just follow the recommended path. If we can't make a clear recommendation, I believe no further PR will substantially improve the situation.

[reactormonk]

The intent for this page should be to guide the user for the first few hours, possibly days. I would argue after a week, this page isn't relevant anymore. So any solution that's batteries included would be preferable. Every difficulty (and choice!) will be losing some people, and let's not filter on that.

[hasufell]

@reactormonk I agree with your motivation. My concern with recommending stack as default choice though is that you quickly get into gritty details, once you need a package outside of stackage. Beginners usually don't care about reproducible builds etc.

[reactormonk]

I wouldn't count reproducible builds as a particularly interesting feature for new people either. I'd go with "managed virtualenv" instead.

The error message is quite a bit better nowadays:

Error: While constructing the build plan, the following exceptions were encountered:

In the dependencies for new-project-0.0.1:
    toml needed, but the stack configuration has no specified version  (latest matching version is 0.1.3)
needed since new-project is a build target.

Some different approaches to resolving this:

  * Recommended action: try adding the following to your extra-deps in /tmp/new-project/stack.yaml:

- toml-0.1.3@sha256:4eac5e516c0e461ceef73150d7a248bce199fc02183074a622c0dab17513ca20,509

[ketzacoatl]

The intent for this page should be to guide the user for the first few hours, possibly days.

I would question that.. how could you possibly know or cover what would be relevant to me and 100k other learners, even if only for the first few hours or days?

If the intent of this page is only to connect the user to
a) the recommended haskell tools you should consider starting with, and
b) the recommended reading material where you can play a "choose your own adventure" game,
we can then achieve that balance you recommend.

Also, b) is just a link like the rest. For this page to be obvious and useful, it should be mostly empty / buttons, not a wall of text.

I would argue after a week, this page isn't relevant anymore.

It should be relevant anytime you want to quickly check/download the latest version of a particular tool that this page offers.

[reactormonk]

I would question that.. how could you possibly know or cover what would be relevant to me and 100k other learners, even if only for the first few hours or days?

Good point. What do you think of a split on Getting Started and Downloads instead? TBH, the only part where I'd actually look for downloads would be under windows, anywhere else I'd just go look for the names and then ask my package manager for them.

[hasufell]

the recommended reading material where you can play a "choose your own adventure" game, we can then achieve that balance you recommend.

That can be a different page. This one is really just about the downloads.

[hasufell]

But yes... given that we can do this split... the download page could just list all major tools and how to get them. It could then say "If you're unsure what tools you need, visit the getting started guide". However... this could again contribute to a more confusing experience, where ppl get redirected all the time and in the end still don't know what to do.

Giving this further thought... I think there should be a separate download page for each platform. Otherwise the page looks overwhelming and cramped.

[ketzacoatl]

What do you think of a split on Getting Started and Downloads instead?

I agree it makes a lot of sense. I am advocating for a comprehensive, and authoritative tutorial series for haskell.org. See https://discourse.haskell.org/t/rfc-documentation-overhaul-on-haskell-org/1942/8 and #61 as well.

I believe the downloads page should be focused on connecting the user to the tools, not explaining them.

With rust, the situation is a little easier (WRT the tools), but compare to their page https://www.rust-lang.org/tools. With Python, it's more complicated, and it shows https://www.python.org/downloads/ is incomplete. Haskell has a slightly different/unique situation, sorta between the two, and our docs should accommodate (IMO that's where the all-encompassing and authoritative doc comes into play - that's where we explain the tools, and help users decide which they would like to use, navigate questions like what is hackage/stackage/etc).

But yes... given that we can do this split... the download page could just list all major tools and how to get them. It could then say "If you're unsure what tools you need, visit the getting started guide". However... this could again contribute to a more confusing experience, where ppl get redirected all the time and in the end still don't know what to do.

Yes, I agree, we need to be careful to not send the user in circles. This is why I believe we need an authoritative doc for onboarding haskell developers.

Giving this further thought... I think there should be a separate download page for each platform. Otherwise the page looks overwhelming and cramped.

IDK that this would be necessary, especially if we defer explanations to a doc and slim this page down to a table of links.

[hasufell]

I'm starting to feel this is getting out of hand and I'm starting to agree that "haskell platform" kind of had the right approach: consider ALL tools (GHC, cabal and stack) part of the main haskell toolchain. So the user will have whatever tool they need for a tutorial, project, whatnot at their disposal.

The user can then just go on following whatever they're doing, whether it's a uni-course utilizing ghci, installation instructions from a project involving stack or cabal instructions.

So we just coin the term haskell toolchain as:

1. GHC
2. cabal
3. stack

Things like ghcup and chocolatey are merely utility tools that may aid in installing one or many of those main tools.

The download page may then refer the user to a getting started page. No choice involved so far. No confusion. Just everything you need. The user will be told to install all 3 of these tools.

[hasufell]

I updated the page like so:

[hasufell]

A link to a getting started guide is obviously TODO, but I think this already is an immense improvement.

[Kleidukos]

Have we managed to emancipate ourselves from hvr now that he's gone missing? Is the PPR updated by someone else?

[hasufell]

Whether he's missing or not... the PPA provides cabal-3.4 and GHC-9.0.1, so I consider this recent.

[gbaz]

I like the thrust of the new changes. If a good getting started guide is produced, the obvious thing to do is to put it as the very first thing in the "documentation" page (https://www.haskell.org/documentation/). That page could use an overhaul as well, but it is better to carefully sort out one thing at a time, rather than let one stand in the way of the next.

[soupi]

I'm definitely in favor of these changes. Thank you for your hard work!
It is worth mentioning that stack does have a starting guide, see (3) Next Steps: https://www.fpcomplete.com/haskell/get-started

[hasufell]

Is there any further input needed for the maintainers of this site to make a decision?

[hasufell]

ping

[jneira]

@hasufell (I assume last comment with screensshots are still from the final version)

I feel i am being a little bit fussy but reviewing the installation instructions it seems to me that

Platform specific instructions

1. Install GHC, cabal-install and haskell-language-server via GHCup
2. To install stack, follow the instructions here

could be interpreted that you have to follow both steps to do a complete install, but in fact both steps usually are alternative

Maybe some short text intro make it clear would be enough?

Otoh haskell-language-server can be installed in windows (and other os's) simply installing the vscode/vschromium and wait it to download automatically. ghcup is a nice way to install it in macos/linux but in windows the most used is the mentioned one (you have to download it manually if you dont use it)
haskell-language-server can be used with ghc+cabali-nstall or stack indistinctly.
Maybe a link to hls install instructions could be handy?

[gbaz]

As per the above discussion, and much else prior, telling people they should pick immediately raises the question of helping them pick or steering them or etc. Doing that becomes complicated and difficult due to the many viewpoints on such questions. Simply pointing them to both is the best way to get an actual page up that is an improvement on the current situation.

[jneira]

As per the above discussion, and much else prior, telling people they should pick immediately raises the question of helping them pick or steering them or etc. Doing that becomes complicated and difficult due to the many viewpoints on such question

Ok if we are gonna try to be neutral i would change the ordered list by an unordered one, it will look less like a list to be completed

Simply pointing them to both is the best way to get an actual page up that is an improvement on the current situation.

Fair enough, totally agree

[gbaz]

This PR looks as though its basically ready to merge. Would be nice to see this taken care of.

[emilypi]

Executive decision: merging.

[hasufell]

Excellent.

The next step seems it would be to create a proper getting started guide (e.g. explaining cabal and stack) that we can then reference from the download page. Is anyone already working on that @Kleidukos @reactormonk @ketzacoatl

[Kleidukos]

The Documentation Task Force can take care of managing this effort.
Thanks @hasufell.

[hasufell]

I was trying to figure out if there is a documented deployment process or if a PR author has to email someone after a merged PR.

I was told that @jaspervdj and @TikhonJelvis are those who can manually deploy, is that correct?

[tomjaguarpaw]

Currently the website is only deployed manually. There is a tentative plan to automate deployment. See, for example, #66.

Recently @TikhonJelvis and @jaspervdj were the two members of the haskell.org committee who had authorisation to log in to the server and manually deploy. However, the server has been moved to a new physical machine so it may well be that the group of authorised people has changed.

I have a plan to discover all these details and write up notes. Please feel free to ping me if you don't see the write-up appear in the README in the near future.

[gbaz]

the server migration shouldn't have affected the authorized people or the deploy process in any way. if that's not the case, please ping the admins with any questions.

[gbaz]

(also the mechanics of the process -- not like procedure of who does it and when, but what commands to run in what order once logged in -- are documented in a file on the server itself, in the appropriate homedir)

[hasufell]

It appears the site has been deployed: https://www.haskell.org/downloads

Thanks everyone!