Remove distro-specific instructions and only leave links #194
Conversation
The links will go out-of-date less quickly so will be easier to maintain. The original patch was by @hasufell with some changes by @tomjaguarpaw.
|
I decided to omit mention of Nix here. @maralorn has agreed to be "owner" of the Nix installation method so he can submit a PR on top with the Nix content that he wishes to maintain. |
|
Please see #170 (comment) for the feedback that was taken into account to produce this PR. |
There was a problem hiding this comment.
Looking good overall. Most of the changes have already had lots of discussion, so the core choices in this PR all make sense.
I left a couple of suggested change to wording, but they're pretty minor—definitely not blockers to get this merged.
Also, as a minor style thing, it's nice to keep Markdown paragraphs on one line. This lets people visually wrap Markdown documents in their editor to whatever width they need while also keeping Git diffs cleaner, especially when different editors hard-wrap in different ways.
site/downloads.markdown
Outdated
| **Do not use the Haskell development tools provided by Arch, they are | ||
| broken.** For more information see |
There was a problem hiding this comment.
| **Do not use the Haskell development tools provided by Arch, they are | |
| broken.** For more information see | |
| **Haskell tools and libraries natively packaged by Arch do not work for local Haskell development.** For more information see |
There was a problem hiding this comment.
Seems like we could be a bit more specific here—if I'm understanding the situation correctly, the Arch approach is fine for stuff like packaging Pandoc for Arch users, but it does not work well for doing Haskell development in general.
There was a problem hiding this comment.
Sure, but someone packaging Pandoc for Arch users already knows that, right? The ratio among visitors to this page of Arch users who are not trying to package for Arch : Arch developers who are trying to package for arch must be something like 1000 : 1, or more right? In which case I think it's probably unhelpful to be more nuanced, even if it is technically correct.
Put another way, the people who would be negatively effected by the lack of nuance in the original wording already know the solution anyway, so I don't think there's much point going out of our way to accommodate them at the expense of presenting a clear message.
There was a problem hiding this comment.
We want to make very clear to users that they shouldn't use arch packages. The word broken is key here.
site/downloads.markdown
Outdated
| 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. |
There was a problem hiding this comment.
I'd lean towards a slightly different tone here:
| 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. | |
| Many operating systems provide GHC, cabal and Stack through their package managers. Note that OS packages can often be out of date. |
OK, I undid the hard wrapping. |
| * [haskell-language-server](https://github.com/haskell/haskell-language-server) (optional): A language server for developers to integrate with their editor/IDE | ||
|
|
||
| ## Installation instructions { #ghcup } | ||
| ## Recommended installation instructions |
There was a problem hiding this comment.
I wonder if we might not want to add something like (All Operating Systems) at the end here so someone glancing at the document will start here. I guess perhaps the recommended covers it, but I'd like to draw eyes to this section rather than the distro packages, since I think on average people will have a better experience avoiding the distro packages.
|
|
||
| *for Linux, macOS, FreeBSD, Windows or WSL2* | ||
|
|
||
| 1. Install GHC, cabal-install and haskell-language-server via [GHCup](https://www.haskell.org/ghcup/) | ||
| 2. To install Stack, follow the instructions [here](https://docs.haskellstack.org/en/stable/install_and_upgrade/) *(N.B. Stack does not support FreeBSD)* | ||
| 2. To install Stack, follow the [Stack installation guide](https://docs.haskellstack.org/en/stable/install_and_upgrade/) |
There was a problem hiding this comment.
Would it make sense for these to be bullet points rather than a numbered list? The numbered list implies to me that you need to follow each step in order, rather than having a choice of install method.
There was a problem hiding this comment.
Yes, that's a good point. However, the numbered list predates this PR so I suggest we leave that for a separate PR.
| * [haskell-language-server](https://github.com/haskell/haskell-language-server) (optional): A language server for developers to integrate with their editor/IDE | ||
|
|
||
| ## Installation instructions { #ghcup } | ||
| ## Recommended installation instructions | ||
|
|
||
| *for Linux, macOS, FreeBSD, Windows or WSL2* |
There was a problem hiding this comment.
Nit-pick, but I wonder if we might want to remove this line altogether in light of the other changes?
|
Thanks for spearheading this @tomjaguarpaw! I agree with Rebecca's small remarks, but overall looks good to me. |
The links will go out-of-date less quickly so will be easier to maintain.
The original patch was by @hasufell. Some changes were made by @tomjaguarpaw.