Further simplification of downloads page

[Bodigrim]

www.haskell.org/site/downloads.markdown

Lines 9 to 17 in bcbc685

	This page describes the installation of the Haskell toolchain, which consists of the following tools:
	* [GHC](https://www.haskell.org/ghc/): the Glasgow Haskell Compiler
	* [cabal-install](https://cabal.readthedocs.io): the Cabal installation tool for managing Haskell software
	* [stack](https://docs.haskellstack.org): a cross-platform program for developing Haskell projects
	* [haskell-language-server](https://github.com/haskell/haskell-language-server) (optional): A language server for developers to integrate with their editor/IDE

I suggest we remove this text: I cannot imagine what kind of purpose it serves nowadays. If I were a novice, I'd be uttterly confused.

• Is Glasgow Haskell Compiler a right tool for me? How is it different from other Haskell compilers? Are there Edinburgh HC or Aberdeen HC?
• "cabal-install is the Cabal installation tool" - ah right, very helpful, thanks, much clearer ;) Again, is it a right tool for me? Do I need to "manage Haskell software" whatever it means? Can I use Cabal to develop Haskell projects?
• "stack is a cross-platform program" is another truism, which is not even true (today stack supports less platforms than cabal because of Mac M1). Can I use it to manage Haskell software, which is seemingly opposed to "develop"?
• We have just defined what consists a Haskell toolchain, but it appears that not all installation options below cover it in full. Then what was the point of such detailed definition? Are Cabal or Stack less optional components than, say, HLS?

I suggest we scrap all of this and free space for two large buttons to download ghcup and stack respectively. If this line of thinking is acceptable, I'm happy to prepare a PR.

[TikhonJelvis]

That sounds like a better way of presenting the information to me. I would expect that almost nobody who would use the downloads page—mostly newer Haskellers—would ever need to go to the GHC website or install GHC manually.

Looks like that's the only part of the page that describes what haskell-language-server is. Presenting it in parallel with Stack/ghcup is confusing, but it's also something that seems worth highlighting even for new Haskellers. How should we present it on the downloads page?

[Bodigrim]

ghcup asks whether to install haskell-language-server during bootstrap process, which provides a reasonable visibility.

[gbaz]

I'm not sure this simplification is helpful -- people need to know that a bunch of different tools end up on their system, and have some idea of what they are -- there's a compiler, there's a build tool (or two!), etc. I'm fine with larger highlighted buttons, but if the descriptions are bad, they should be fixed. At some point, someone will want to know the difference between ghc, stack, and cabal, and why all three are on their system.

[Bodigrim]

My point is that current explanation fails to explain and is worse than no explanation at all. I believe we all know that it is vague and ambiguous for political reasons, so it may be hard to come up with a better alternative. At a risk of being ostracized by both parties, I'd rephrase it this way:

To write Haskell you need a compiler (GHC, Glasgow Haskell Compiler) and a build tool. For historical reasons there are two competing build tools, Cabal and Stack, which are largely interchangeable for educational purposes. To get started you can either use ghcup, which is an installer tool and manager for GHC, Cabal and/or Stack; or install Stack and let it download GHC on its own. ghcup can additionally install Haskell Language Server (HLS) to support IDE features in your editor.
[Two large buttons]

[tomjaguarpaw]

Thank you very much for prompting this discussion. I agree that the current presentation bears significant improvement. I would suggest you turn this into a PR, as long as you are willing for the PR discussion to be long and perhaps somewhat contentious. However, I believe that the discussion is important in refining the proposal into something with broad approval.

There is a (relatively) recent new user experience report you might like to read for inspiration: #136

[tomjaguarpaw]

At some point we ought to consider whether this should be called the "downloads" page. It's really the 'installing Haskell" page. Use of the word "downloads" for "go here if you want to install my software" is an anachronism. I don't think people are used to that kind of language any more.

[tonyday567]

Following up from my side comment in #170, specifically:

Having the big four (GHC, cabal-install, HLS and stack) at the top is confusing. It makes more sense to headline the whole page with a link to GHCup, and then suggest to follow the provided links if you want to install the toolchain manually. Add in a comment that stack is an alternative toolchain installation option to GHCup in the stack section, and it flows well.

This order would help clarify the actual 'Installation Instructions' 1. 2. list which is confusing as it stands. GHCup installs stack if you want but it is not listed as such. And then the instructions could be easily interpreted as having to complete both steps in order to install the whole toolchain - it needs at least an or.

I happen to like the listing of the 4 main elements of the toolkit - it provides a bridge between "trust us and use our *up method" and those users who would like to know what it puts on their machine.

But if it is removed and #170 adopted, then the page approximately reads as follows:

for Linux, macOS, FreeBSD, Windows or WSL2
Install GHC, cabal-install and haskell-language-server via GHCup
To install stack, follow the instructions here (N.B. stack does not support FreeBSD)

And this, to my eye, is a confusing mess. To repeat:

• stack is also installed by GHCup, and users will be confused when they find stack in the GHCup list
• There should be an 'or' between 1 and 2. It reads as though you need to do both steps.
• There is no OS alternatives to the first sentence, so it serves no purpose.

Given all the deletions, it would become much clearer if the whole thing is replaced by two buttons, GHCup and stack, or one if you consider stack to be wrapped by GHCup like we consider the other 3 elements to be.

[tomjaguarpaw]

Regarding

stack is also installed by GHCup, and users will be confused when they find stack in the GHCup list

There should be an 'or' between 1 and 2. It reads as though you need to do both steps.

and

it would become much clearer if the whole thing is replaced by two buttons, GHCup and stack, or one if you consider stack to be wrapped by GHCup

it is currently politically untenable to treat ghcup and stack on anything other than an equal footing. I agree that the choice between stack/cabal and stack/ghcup makes things rather confusing for new users, but I don't see a way through that in the short term. Making any progress on that requires a lot of attention to trust-building. I think it's possible, but it requires concerted effort.

[tomjaguarpaw]

Regarding,

There is no OS alternatives to the first sentence, so it serves no purpose.

are you referring to

for Linux, macOS, FreeBSD, Windows or WSL2

Indeed there are no alternatives to those OSes, but on the other hand we want to make it clear what OSes are supported. Can you suggest a change of wording you would like to see?

[tonyday567]

Yes. I am mostly pointing out that the grammatical construction suggests that there are other instructions for other OSes.

Ultimately, it would be best to replace it with "it looks like you are running MacOS" or "it looks like you are running an OD not supported by GHCup".

Maybe something like:

GHCup supports Linux, macOS, FreeBSD, Windows and WSL2, and stack supports Linux, macOS, Windows and WSL2. There are many alternative ways to install the Haskell toolkit if you are running another OS. Each component of the toolchain installed by GHCup has instructions for installation, including building from scratch.

and then place the existing dot points for the 4 pieces after that.

I would be happy to draft a PR along these lines if you think it has a chance of being accepted.

[tonyday567]

it is currently politically untenable to treat ghcup and stack on anything other than an equal footing. I agree that the choice between stack/cabal and stack/ghcup makes things rather confusing for new users, but I don't see a way through that in the short term. Making any progress on that requires a lot of attention to trust-building. I think it's possible, but it requires concerted effort.

I mean no disrespect to the stack project or to the notion that stack is a great alternative installation method. It has personally saved me on many an occasion. stack should be celebrated widely and enthusiastically.

However, I believe we have community consensus that HLS is privileged. There are 4 components; stack, GHC, cabal and HLS, that we consider to be core toolkit, if I read the community right. The problem with stack and GHCup being branded as equal is that they are not isomorphic with repect to HLS. For very good technical reasons, the recommended way to install HLS is via GHCup and not stack or cabal. To quote https://haskell-language-server.readthedocs.io/en/latest/installation.html:

Direct installation from Source, while possible via cabal install haskell-language-server and stack install --stack-yaml stack-.yaml, is not recommended for most people. Said command builds the haskell-language-server binary and installs it in the default Cabal binaries folder, but the binary will only work with projects that use the same GHC version that built it.

This is where the puck is.

[ketzacoatl]

I cannot imagine what kind of purpose it serves nowadays. If I were a novice, I'd be uttterly confused.

I agree the current wording is confusing, however I would like to believe the purpose was/is to inform about the options. On a page with more than one option, why you want one or another choice should be explained such that a reader can make a good decision for themselves. I think there needs to be a page, or portion of a page, which describes these tools and how they relate, or at least clarifies why you might want one or another.

[ParetoOptimalDev]

it is currently politically untenable to treat ghcup and stack on anything other than an equal footing. I agree that the choice between stack/cabal and stack/ghcup makes things rather confusing for new users, but I don't see a way through that in the short term. Making any progress on that requires a lot of attention to trust-building. I think it's possible, but it requires concerted effort.

I mean no disrespect to the stack project or to the notion that stack is a great alternative installation method. It has personally saved me on many an occasion. stack should be celebrated widely and enthusiastically.

However, I believe we have community consensus that HLS is privileged. There are 4 components; stack, GHC, cabal and HLS, that we consider to be core toolkit, if I read the community right. The problem with stack and GHCup being branded as equal is that they are not isomorphic with repect to HLS. For very good technical reasons, the recommended way to install HLS is via GHCup and not stack or cabal. To quote https://haskell-language-server.readthedocs.io/en/latest/installation.html:

Direct installation from Source, while possible via cabal install haskell-language-server and stack install --stack-yaml stack-.yaml, is not recommended for most people. Said command builds the haskell-language-server binary and installs it in the default Cabal binaries folder, but the binary will only work with projects that use the same GHC version that built it.

This is where the puck is.

Yes, unless stack starts installing a compatible hls for you i'd agree they aren't equal and ghcup should be preferred despite many UX deficiencies in cabal-install vs stack.

[Bodigrim]

The situation became less pronounced after #220 and #221, I guess it's fine to close for now.