-
Notifications
You must be signed in to change notification settings - Fork 93
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Redo the entire download page, fixes #12 #71
Conversation
The page looks really great, congrats |
Good catch.
Yes, this has been discussed previously. To re-iterate and expand:
|
019f81e
to
b806bc2
Compare
b806bc2
to
9dcf082
Compare
This statement is contradictory to your listing of
Did you mean to say 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. |
I don't think so.
No, the term coined here was "Haskell toolchain". And I defined
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.
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. |
Since the platform now redirects people to chocolatey or ghcup I support switching the downloads page to point to those resources directly. |
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.
There will be people who disagree with
If this were the expressed goal, I'd agree, but here's where I think we get off track:
I am a
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. |
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.
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:
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. |
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. |
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
This is definitely not the intent behind Contrast this with
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.
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:
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 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. |
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:
Again, thank you for discussing improvements to this page, it's important work. |
That may be true. But just to name a few things that keep confusing newcomers:
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 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.
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.
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.
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:
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. |
Ok, what about this: guiding the user through 3 choices:
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. |
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. |
@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. |
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:
|
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 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.
It should be relevant anytime you want to quickly check/download the latest version of a particular tool that this page offers. |
Good point. What do you think of a split on |
That can be a different page. This one is really just about the downloads. |
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. |
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).
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.
IDK that this would be necessary, especially if we defer explanations to a doc and slim this page down to a table of links. |
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:
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. |
ee4cf50
to
fb7f9a6
Compare
A link to a getting started guide is obviously TODO, but I think this already is an immense improvement. |
For help with Haskell and GHC in general, see the links mentioned [above](#help). For Stack itself there are also the following resources: | ||
Packages from the PPA can be installed as follows: | ||
```bash | ||
sudo add-apt-repository -y ppa:hvr/ghc |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Have we managed to emancipate ourselves from hvr now that he's gone missing? Is the PPR updated by someone else?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Whether he's missing or not... the PPA provides cabal-3.4 and GHC-9.0.1, so I consider this recent.
fb7f9a6
to
e4d3540
Compare
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. |
I'm definitely in favor of these changes. Thank you for your hard work! |
Is there any further input needed for the maintainers of this site to make a decision? |
ping |
@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
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 |
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. |
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
Fair enough, totally agree |
This PR looks as though its basically ready to merge. Would be nice to see this taken care of. |
Executive decision: merging. |
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 |
The Documentation Task Force can take care of managing this effort. |
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? |
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. |
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. |
(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) |
It appears the site has been deployed: https://www.haskell.org/downloads Thanks everyone! |
@mattbaumann @gbaz @emilypi
Pictures: