Added get-started page. #227
Conversation
That's unfortunate :/ Ideally, we should be getting all of our dependencies from a Nix cache. If people need to build stuff like Pandoc from source, we should do something about it:
I can't look into this just now, but I'll poke around soon. I recently did an aggressive Nix GC on my main development machine, so I'll be able to see what gets built from cache myself :P |
Not everyone (including me) uses Nix on their local machines! The |
|
Oh, good point. If @Martinsos was building hakyll + dependencies with cabal and not using Nix, it'll always build from source and I don't know if there's anything we can do about that. |
|
Right, I think @Martinsos was just saying "Pandoc is taking 15 minutes like it always does", not suggesting that there was anything wrong. |
Martinsos
force-pushed
the
getting-started
branch
from
6015c37 to
91218ca
Compare
|
Sorry for being absent so long, I got overwhelmed by private and professional duties -> but I am back now, to finalize this PR! @tomjaguarpaw correct, it wasn't unexpected for me that it was taking so long to build (pandoc), I just didn't have time at the moment to wait for it to finish. @TikhonJelvis correct, I was building with Cabal, so it was taking very long. The reason I didn't build with Nix was that I was getting an error with wrong encodings, which I now documented in this old issue that claims it was fixed, but it seems an issue is still here to some degree. I managed to fix it by following your advice from the related PR though, by setting But to get back to the PR -> what are the next steps, what do we need to do to get it merged? Reminder that this PR is just a reincarnation of previous PR, where we (me, @soupi, @lsmor, and @tomjaguarpaw) chiseled and polished it until everybody was satisfied. It got PR approval from @TikhonJelvis and @jfoutz . I guess this PR will need those approvals again? The old PR got closed by accident (as @tomjaguarpaw explains here ) so this one got opened instead, with the same changes. From what I last understood based on what @TikhonJelvis said here, this is basically it, and we "just" need to clear it with the committee?
|
|
@TikhonJelvis @tomjaguarpaw please consider the kind of a message you are sending to contributors when they invest tens of hours of their time crafting PRs trying to improve the state of things only for them to sit completely ignored for months. If you don't have time to review PRs, consider this simple heuristic - is this PR a step in the right direction, or is it completely off-mark with your vision? |
|
We're all volunteers here with very limited time. People who want to contribute must drive the programme forward. I'm sorry about this, but it's just the way things are with the current staffing levels. |
To expand with some actionable advice:For those who want to make contributions to the website, the most important thing to be know is that the Haskell.org committee, who are responsible for approving changes to the website, have very little free time. Many of us are already donating hours of each week to various tasks to improve things for the Haskell community, not only through Haskell.org but also the HF and other projects. That means that, regrettably, for anything but the smallest tweaks to the website, the proposers themselves must essentially "project manage" the PR themselves. They will have to take responsibility for continuing to push to make sure their comments have been read and get replies. They will have to push to clarify the terms under which the contribution will be accepted. This is a highly undesirable situation and I'm not saying this because I like it or because I think it's the way things should be. Rather, I'm saying it because it's a fact and accepting the fact will make it easier to understand how to get things done. Some suggestions to PR authors about getting their PRs reviewed and merged:
About this PRMartin's PR here is one that changes the "nature" of the site so it's going to take longer to deal with. After #220 this PR actually became a "less big" change, so hopefully that will make it easier to deal with. That said, the PR could still be simplified by removing seemingly incidental changes, for example
Perhaps these things are trivial, but as a reviewer I don't know that! To review it I have to pay close attention to what that changes in the behaviour and presentation of the site, make sure it hasn't broken anything important, and be prepared to undo the breakage at the cost of my own time if, after merge, it turns out it has broken something that escaped my notice. That's a large burden for me to want to take on. This PR could be made simpler to merge by removing those seemingly incidental changes. (And if they're not incidental that needs to be called out loudly!) Some suggestions for people who want to improve the system of maintaining and updating the website itselfTo reiterate, the current system is very undesirable, but it's a consequence of the resources available to us. If you want to make this whole process run more smoothly, not just contribute PRs:
Footnotes
|
site/downloads.markdown
Outdated
| <p><a data-toggle="collapse" href="#collapse-linux" class="btn btn-xs btn-primary">Show Linux distros</a></p> | ||
| <p><a data-toggle="collapse" href="#collapse-linux" class="btn btn-xs">Show Linux distros</a></p> |
There was a problem hiding this comment.
Is this change (and the similar ones) necessary?
There was a problem hiding this comment.
What happened here is that I removed "btn-primary" class from the 4 buttons at the bottom of the Downloads page, where each of these buttons on click expands into detailed instructions for installation of Haskell toolchain via native OS package manager for specific distribution.
This is what it looked like before:
This is what it looks like now:
I removed it because I felt confident that it was a mistake in the earlier design. The main thing we want visitors to focus on this page is GHCup, then explanation of the toolchain, and only then potentially the installations via native OS package manager. So it is the part of the page that we want to attract the least of the attention, we even have text that says this method of installation is not recommended and should ideally not be used, but then it uses the btn-primary class, which is to be used for the buttons that should be most emphasized, usually used for the CTA (Call To Action) button.
I still think this is a clear improvement and don't see what could the arguments against it be, but I can revert this change if needed.
There was a problem hiding this comment.
OK, that makes sense! Can you please submit that as a separate PR? That one's easy to merge. No need to delay it by mixing it with a bigger one.
There was a problem hiding this comment.
In fact I made the PR myself: #239
Could you copy across those screenshots to that PR?
site/index.html
Outdated
| <div class=" row "> | ||
| <div class=" span12 col-sm-12 hidden-xs"><br></div> | ||
| <div class="row" > | ||
| <div class=" span12 col-sm-12 hidden-xs"><br><br></div> | ||
| </div> | ||
| <div class=" row " style="display: flex; align-items: center"> | ||
| <div class=" span6 col-md-6"> | ||
| <div class="branding"> | ||
| <br class="hidden-xs"><img src="/img/haskell-logo.svg" class="img-responsive"> | ||
| <h4 class="summary">An advanced, purely functional programming language</h4> | ||
| <br class="hidden-xs"> | ||
| <img src="/img/haskell-logo.svg" class="img-responsive"> | ||
| <h4 class="summary">An advanced, purely functional programming language</h4> | ||
| </div> | ||
| </div> | ||
| <div class=" span6 col-md-6"> | ||
| <div class="branding sample"> | ||
| <br class="visible-xs visible-sm"> | ||
| <h4 class="tag">Declarative, statically typed code.</h4> | ||
| <div title="This example is contrived in order to demonstrate what Haskell looks like, including: (1) where syntax, (2) enumeration syntax, (3) pattern matching, (4) consing as an operator, (5) list comprehensions, (6) infix functions. Don't take it seriously as an efficient prime number generator." class="code-sample"> | ||
| <pre><span class='hs-definition'>primes</span> <span class='hs-keyglyph'>=</span> <span class='hs-varid'>filterPrime</span> <span class='hs-keyglyph'>[</span><span class='hs-num'>2</span><span class='hs-keyglyph'>..</span><span class='hs-keyglyph'>]</span> | ||
| <div class="row" id="code-example"> | ||
| <div class="branding sample"> | ||
| <br class="visible-xs visible-sm"> | ||
| <h4 class="tag">Declarative, statically typed code.</h4> | ||
| <div title="This example is contrived in order to demonstrate what Haskell looks like, including: (1) where syntax, (2) enumeration syntax, (3) pattern matching, (4) consing as an operator, (5) list comprehensions, (6) infix functions. Don't take it seriously as an efficient prime number generator." class="code-sample"> | ||
| <pre><span class='hs-definition'>primes</span> <span class='hs-keyglyph'>=</span> <span class='hs-varid'>filterPrime</span> <span class='hs-keyglyph'>[</span><span class='hs-num'>2</span><span class='hs-keyglyph'>..</span><span class='hs-keyglyph'>]</span> |
There was a problem hiding this comment.
Are these changes necessary?
site/index.html
Outdated
| <br class="hidden-sm"> | ||
| <br class="hidden-xs hidden-sm"> | ||
| <br class="hidden-xs hidden-sm"> | ||
|
|
There was a problem hiding this comment.
Are these changes necessary?
There was a problem hiding this comment.
These are the final <br>s I added for the purpose of centering the content.
|
To add some actionable advice for @Martinsos specifically: If you undo the seemingly incidental changes (the ones I have highlighted above) then it's more likely that the decreased cognitive load will mean I can consider the main functional changes more quickly. That said, I'm sorry but I can't guarantee any level of turnaround time on this. Thank you again for your contributions. They are very welcome, but I and the other members of the committee have an awful lot of things on our plates. |
|
@soupi thanks for advocating for me / contributors! @soupi and @tomjaguarpaw : No worries, I have also been absent for some time, so I didn't expect this to get merged immediately, but when the maintainers will have time to review, and I did expect that to possibly take some time. I believe I am already doing the pushing @tomjaguarpaw that you described is expected: that is why I wrote last comment where I made sure to repeat as much context as I can, with links for references, so maintainers don't have to do the reminding on their own, and to speed up the loading of the context for them. That is also why I am asking questions about the next steps, to ensure they are clear and that we can proceed. @tomjaguarpaw what you wrote about incidental changes makes perfect sense -> as a reviewer, I also appreciate when I don't have to guess the motivation and/or impact of changes, but instead that is made clear to me by the author. I will take some these days (maybe even today but not sure) to remind myself why I did specific change and will either provide detailed motivation / explanation or will remove them, so that PR can proceed. Couple of thoughts unrelated to this specific PR, but related to reviewing PRs in general:
Anyway thanks all, and I will reach out soon with details on those accidental changes! |
|
Thanks @Martinsos for sharing your thoughts. To be clear, I would say that you've been doing an excellent job of pushing, being proactive, and sharing important context, both here and on other forums like Discourse. My comments were meant as general information, not for you specifically. (Although perhaps you also already realised that!) One thing that would have helped here is to stay in contact more frequently. It's hard for me to get back into the state I was in 2.5 months ago when we last communicated about this. But I appreciate that you have been as busy as us, so frequent contact is not always possible. I like the idea of explaining more in the README to help newcomers. I also like your summary of loosening criteria on PRs. However, for www.haskell.org specifically, I think I would be reluctant to loosen the criteria. Anyway, I'll bear it in mind. |
|
I realised that there is a way of getting 95% of the benefits of system-level changes I described above with 5% of the effort: every PR author should attempt to find an individual from the committee who will be directly responsible for that particular PR, and champion its progress through review and committee vote. That's much easier than finding a directly responsible individual for the entire website. Any PR that can't obtain a champion is unlikely to be successful in any case, and that will reduce the risk of contributors putting in a lot of work to a PR only for it to be rejected a long time later. I will volunteer to be the champion for this PR, because I have discussed this particular issue with @Martinsos at length in various places. So @Martinsos, please revert the non-essential changes as I suggested above (or explain why they are essential) and come back to me. Then I will decide on the next steps. |
There was a problem hiding this comment.
I reviewed your comments @tomjaguarpaw !
To summarize quickly:
-
Changes I did on Downloads page I believe are a no-brainer fix of wrong emphasis of links -> I explained more in the additional comment. I can remove that change if needed though.
-
On index.html, I commented on all the changes I did. I believe there is only one that is potentially questionable, and that is adding the
<br>s. The rest of the changes is just fixing old Bootstrap mistakes or using Bootstrap to correctly align stuff -> git shows it as more changes due to changed indentation.
I commented all of this in more details in specific comments so please check it out.
As for adding <br>s, which is probably the only thing that is a bit controversial, here is what it looks like without them (so no change):
and here is what it looks like with them as I added them now:
I explain the reasoning behind it in a more specific comment.
site/downloads.markdown
Outdated
| <p><a data-toggle="collapse" href="#collapse-linux" class="btn btn-xs btn-primary">Show Linux distros</a></p> | ||
| <p><a data-toggle="collapse" href="#collapse-linux" class="btn btn-xs">Show Linux distros</a></p> |
There was a problem hiding this comment.
What happened here is that I removed "btn-primary" class from the 4 buttons at the bottom of the Downloads page, where each of these buttons on click expands into detailed instructions for installation of Haskell toolchain via native OS package manager for specific distribution.
This is what it looked like before:
This is what it looks like now:
I removed it because I felt confident that it was a mistake in the earlier design. The main thing we want visitors to focus on this page is GHCup, then explanation of the toolchain, and only then potentially the installations via native OS package manager. So it is the part of the page that we want to attract the least of the attention, we even have text that says this method of installation is not recommended and should ideally not be used, but then it uses the btn-primary class, which is to be used for the buttons that should be most emphasized, usually used for the CTA (Call To Action) button.
I still think this is a clear improvement and don't see what could the arguments against it be, but I can revert this change if needed.
site/index.html
Outdated
| <div class="row" > | ||
| <div class=" span12 col-sm-12 hidden-xs"><br><br></div> | ||
| </div> |
There was a problem hiding this comment.
Here I did 2 changes:
-
I added additional
<br>. I added this<br>and a couple of others below in some places in order to put the "get started" button close to the center of the page, and push Videos section closer to the bottom of it. I did this guided by the typical advice for designing a landing page -> you want your CTA to be the most attractive thing to click that is visible above the fold. In our case that is "getting started" button. Vidoes section is still partially visible above the fold, but is a bit more down and therefore looks more like smth additional to explore than the main thing to look at. -
I closed the div that is Bootstrap row here, instead of letting it also capture the stuff below. One Bootstrap row is always organized as 12 columns, but it was misused here, because somebody first added an element that spans all 12 columns, and then below one more element that spans 6, and then one more that spans 6!
The way Bootstrap handles such situation result in ok result, but it is semantically incorrect. So I closed this div here, so it contains only one element of 12 columns. This element of 12 columns is anyway used to add vertical empty space in the whole width of the page, so it makes perfect sense that it is a standalone row.
This is merely a Bootstrap fix of the previous mistake somebody did.
site/index.html
Outdated
| <div class=" span6 col-md-6"> | ||
| <div class="branding"> | ||
| <br class="hidden-xs"><img src="/img/haskell-logo.svg" class="img-responsive"> | ||
| <h4 class="summary">An advanced, purely functional programming language</h4> | ||
| <br class="hidden-xs"> |
There was a problem hiding this comment.
Here I just formatted the code to be consistent.
There was a problem hiding this comment.
That's fine. I think that it would be easier to have that in a separate PR, or not at all. It doesn't seem like a big deal but just makes this PR bigger and harder to understand.
site/index.html
Outdated
| <div class="row" id="code-example"> | ||
| <div class="branding sample"> | ||
| <br class="visible-xs visible-sm"> | ||
| <h4 class="tag">Declarative, statically typed code.</h4> | ||
| <div title="This example is contrived in order to demonstrate what Haskell looks like, including: (1) where syntax, (2) enumeration syntax, (3) pattern matching, (4) consing as an operator, (5) list comprehensions, (6) infix functions. Don't take it seriously as an efficient prime number generator." class="code-sample"> | ||
| <pre><span class='hs-definition'>primes</span> <span class='hs-keyglyph'>=</span> <span class='hs-varid'>filterPrime</span> <span class='hs-keyglyph'>[</span><span class='hs-num'>2</span><span class='hs-keyglyph'>..</span><span class='hs-keyglyph'>]</span> |
There was a problem hiding this comment.
The only thing I did here was wrapped all this into a div that has Boostrap class "row".
I need to do this in order to later add a get-started button below it, which is also in its own "row". This is how it is done in Bootstrap.
I didn't touch any of the existing html here, git is showing it as a change only because of the indentation.
site/index.html
Outdated
| <br> | ||
| <br class="hidden-sm"> | ||
| <br class="hidden-sm"> | ||
| <br class="hidden-xs hidden-sm"> | ||
| <br class="hidden-xs hidden-sm"> |
There was a problem hiding this comment.
Here I added 2 <br class="hidden-sm">, which add some extra space on the small monitors. This is for the same purpose as the other <br>s I added -> to center the get-started button in the page and push Videos section a bit lower.
site/index.html
Outdated
| <br class="hidden-sm"> | ||
| <br class="hidden-xs hidden-sm"> | ||
| <br class="hidden-xs hidden-sm"> | ||
|
|
There was a problem hiding this comment.
These are the final <br>s I added for the purpose of centering the content.
Makes sense. What we usually do is ask around the team who wants to handle it -> be it explaining why not to do it, or be it pushing it further. That person can then assign themselves on that PR as asignee. |
tomjaguarpaw
force-pushed
the
getting-started
branch
from
91218ca to
2e9cd95
Compare
tomjaguarpaw
force-pushed
the
getting-started
branch
from
2e9cd95 to
84f35dc
Compare
|
I split off and now this one does a lot fewer things, i.e. only the getting started guide. |
|
I've also pushed on top some minor stylistic suggestions. Feel free to dispute them if you don't like any of them. I'll leave it there for now, as I am getting some decision fatigue ... |
Co-authored-by: Tom Ellis <[email protected]>
Martinsos
force-pushed
the
getting-started
branch
from
f13b759 to
62e5551
Compare
|
@tomjaguarpaw good idea to split them! For the future though, I would advise that you don't do the splitting, if possible, but leave it to the PR author (in this case me). What you did here is the following:
What this resulted with:
Not to mention that you said yourself you don't have much time, and I acknowledged that is not a problem and that I am here to help push this forward. But then you spent your time to make all this splitting that I could have easily done + got me into a situation where I need to spend time reviewing it. What I think would have been the best course of action is if you asked me to do the split. We anyway got to the point where we clearly delineated different sets of changes that emerged in this PR (get-started page vs links on download page vs landing page design fix), which is obvious from the latest comments, and I would be easily able to create 2 new PRs. What I did now is following:
As for your commit with style improvements: I dropped the changes where you replaced newlines in markdown with double space, because I think that just reduces readability, but we can discuss that if you wish, the rest I kept, and put note to myself to run text through grammarly next time (although I have done it at some point but probably not again once after PR review). All together, I believe you did this with good intentions, because you wanted to speed things up and reduce the amount of work I would have to do with splitting, so I don't have any hard feelings and appreciate the effort. That said, I would advise in general not to take control in this way over contributor's PRs, to avoid situations like this (confusion, loss of authorship, ...). My rule when handling contributors is that I don't take over control unless it is clear they gave it up or are unable to make the changes. That means that I will first ask them if they want to do the change: "Hey, I think we should split this into 3 PRs, in the lines of what we discussed, is that sometihng you could do?". If I think it will be a bother for them and I want to offer my help, I will add "If needed I can do it for you", but will wait for their answer. If they don't respond for some time or they say they would rather I do it, then I might do it, but not before. I would also try in that process to preserve their authorship, be it through careful cherrypicking, or if nothing else, by listing them as co-authors. |
|
OK, sorry for the confusion. I misunderstood the meaning of you granting maintainers the right to push to your branch, and for what it's worth I did credit you in the commit messages of the new commits: 1, 2. It's thoughtful of you to add me as a co-author but please don't go to too much trouble to do that in the future. Personally am not too concerned about credit. I just want the site to improve. |
Yes I noticed that (mention in the commits), and as I said I have no doubt you didn't want to take any credit away. Adding a co-author is as easy as adding one line to commit message, so no problem there. Also pls do note that we are in very different positions here: you as an established contributorin HS ecosystem, maintainer of haskell.org, and member of HF and similar, why I am merely a relatively fresh contributor. And while I am primarily doing this to improve the site, which is why I took so much time and jumped through all the hoops, I also welcome the opportunity to build a bit of my credibility in the Haskell community while doing it. I care about Haskell and this might allow me to get involved further in the future, and possibly for my word to have a bit more weight in some situations. So when dealing with new contributors like me, if I was a maintainer, I would be very careful to give all the credit where such can be given, since that is the only thing they get really, and is a good way to encourage them to feel as a part of the community, and shows that their contribution is appreciated. And comment with a mention in a PR is big difference next to commit authorship and getting listed on gh repo as a contributor. |
|
OK, I'm happy to credit you for your work in whatever way you think appropriate. I have made some edits and submitted a PR to your branch: Martinsos#1 |
* Link to VSCode webpage * Promote Haskell Discourse above Reddit because Haskell Discourse is a Haskell-official site * Set up _a_ Haskell dev environment * dev environment -> development environment Writing it out in full is probably a bit clearer for new users. * Lower case "toolchain" There's no specific thing called "Haskell Toolchain". We're just talking about the toolchain for Haskell. * Fix link text and location * Fix link location * Lower case "Get started" * Use parentheses instead of arrows * "the full list of learning resources" -> "a bigger list ..." * ghci -> GHCi * "manage Haskell toolchain" -> "manage the Haskell toolchain" * Remove superfluous "for you" * Grammar tweaks and binary -> executable * Remove mention of runghc, to reduce complexity I'm pretty sure no one really uses runghc. It's probably better to avoid mentioning it. * Avoid talking about "Haskell communities" (plural) because this is confusing given that we've just talked about "Haskell community" (singular) * Remove needless words * Punctuation * Grammar * this -> Cabal (i.e. be specific) * "it -> GHC" (i.e., be more precise) * "this" -> "HLS" (i.e., be more precise) * -> to : * "Join the community" -> "Participate in the community" The Haskell community is not really something you can "join", per se. * Whitespace * Don't start a new paragraph so often
Thanks, although my intention behind my last message was not to get you to credit me, since that was already solved, but to offer you a different perspective (of a contributor) on the value of crediting in general (since it felt like you dismissed it in your previous message), hoping it would be useful to you when handling future contributors. Thanks for the PR, I saw it and merged it as it is -> I think that is good enough, I can open additional PRs for discussion of smaller tweaks if I find it important enough, but later once we merge this PR. |
|
OK, then thank you also for sharing your perspective. |
|
Dear Haskell.org committee, @Martinsos has kindly written a Getting Started page for www.haskell.org. I would like to recommend that we accept it. According to our PR policy this probably requires a committee majority, i.e. four committee votes in favour. |
|
|
||
| # Get started | ||
|
|
||
| Welcome, new Haskeller! Read on to quickly set up your Haskell development environment, execute your first lines of code, and get directions for further learning. |
There was a problem hiding this comment.
I like the phrasing here. "Welcome, new Haskller!" is a great intro.
| ### Editor | ||
| [**Visual Studio Code**](https://code.visualstudio.com/) ([**VSCode**](https://code.visualstudio.com/)) is a popular choice with well-supported Haskell integration. Install the [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. 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). | ||
|
|
||
| ## Running your first lines of code |
There was a problem hiding this comment.
I wonder if we could bring the interactive tutorial over from the main page to here to make some of this a bit more interactive?
There was a problem hiding this comment.
I think that's probably worth delaying to a separate PR.
There was a problem hiding this comment.
That is interesting idea! I was considering a bit what to do with it, since it feels like right now we have two CTAs on landing page -> one is "Get Started" button, second is "Try it" prompt. Ideally there would be just one. But, if we would try to include it in the get-started page, I think it would side track us -> on get-started we are getting them to install tooling, and then we want them to use what they installed and try haskell through that, so when they are done with the get-started page, they have everything installed and have an idea how to use it -> they now feel ready to play with Haskell on their machine and had their first victory.
So at the moment I don't have a good idea how to plug in Try It into get-started. One option might be to remove it from landing page, but that does feel a bit bad since it is so cool. So I would probably just leave it for the time being, I don't think it hurts.
site/get-started.markdown
Outdated
| By participating in the Haskell community you be able to ask for help and learn about new developments in the Haskell ecosystem. Some of the most popular places to interact with the community are: | ||
|
|
||
| - [Haskell Discourse](https://discourse.haskell.org/) | ||
| - [r/haskell](https://www.reddit.com/r/haskell/) |
There was a problem hiding this comment.
Might be worth explicitly mentioning that this is reddit?
There was a problem hiding this comment.
Good point! I changed it to "Haskell subreddit".
|
|
||
| We recommend joining right now, and don't be shy to ask for help! Check [https://www.haskell.org/community](https://www.haskell.org/community) for a full list of resources relating to the Haskell community. | ||
|
|
||
| ## Next steps |
There was a problem hiding this comment.
I'm not entirely sure about this particular list of resources, but I like the general idea of picking a couple of free resources as a starting point.
There was a problem hiding this comment.
We can discuss it, we had a bit of conversation on it here on the PR and ended up with this. I am big fan of LYAH (even though it is somewhat outdated), and also like the new book with building static blog generator, think they are very accessible and practical. I don't know much about the materials from the uni that we listed but they were on top of course list of Documentation page on haskell.org .
We can modify this if you have better ideas!
| A complete Haskell development environment consists of the Haskell toolchain (compiler, language server, build tool) and an editor with good Haskell support. The quickest way to get this set up is to: | ||
|
|
||
| 1. Use **GHCup** to install and manage the Haskell toolchain. | ||
| 2. Use [**VSCode**](https://code.visualstudio.com/) as the editor, with the Haskell extension installed. |
There was a problem hiding this comment.
How would you feel about linking to the free VSCodium builds instead of the non-free version?
There was a problem hiding this comment.
I understand the motivation, but I don't think that is beneficial for the goal of reducing friction to get new people to learn Haskell. Those that care about open source will probably reach out vscodium anyway, while for those that don't, this probably isn't the best moment to introduce it -> we are already introducing Haskell which is complex enough.
If this will be a stopper for merging, I can change it to VSCodium, but I think it sends the wrong message to newcomers to Haskell.
|
|
||
| In your editor, create a new file named `hello.hs`. Write the following in it: | ||
| ```hs | ||
| main = do |
There was a problem hiding this comment.
| main = do | |
| main :: IO () | |
| main = do |
Not only is it best practice to give type signatures to top level bindings, but I feel like types should make an appearance somehow, since it's such a core part of the language.
There was a problem hiding this comment.
That is a good point, but I don't think :: IO () will mean much to them at this point. If it was myNumber :: Int, I think they could grok what it is, but I don't think IO () would mean anything at all. And the point is to just get them interested and get something running, they will learn proper stuff after this guide.
So I am soemwhat for showing off types, if we can do it in an easy way, but I don't think this example with IO would fall under that.
|
|
||
| ## Writing your first Haskell program | ||
|
|
||
| In your editor, create a new file named `hello.hs`. Write the following in it: |
There was a problem hiding this comment.
Just nit-picking here, but it's unusual for .hs file titles to not be capitalized.
There was a problem hiding this comment.
@aaronallen8455 Actually, the GHC guide uses the same example: hello.hs
There was a problem hiding this comment.
Yes, and I understand why - so that the resulting executable has the desired name. It just bothers me slightly that it diverges from the conventional naming pattern for .hs files.
There was a problem hiding this comment.
We'd see more lowercase .hs files if Haskell were a bit more convenient for scripting :). I've written a few scripts in Haskell with #!/usr/bin/env runhaskell and it seemed natural to give them lowercase names.
There was a problem hiding this comment.
We can do whatever you like here, I don't mind. I think hello.hs is ok for this quick guide, they will learn soon anyway more about Haskell, I don't thikn this will give them some wrong ideas.
I also write scripts in haskell with lower name, when I am interpreting them with cabal or just with ghci and they are not part of any project, and this is such instance, so that is also a good argument for lower name yes.
|
Thanks everyone, I responded to all the comments and pushed one small change (r/haskell to "Haskell subreddit")! |
|
Thanks for the reviews all. 5 votes in favour is enough to merge. I'm sure Martin will welcome suggestions for tweaks. |
|
Awesome, thank you everybody, and @tomjaguarpaw for pushing this with me! |
@tomjaguarpaw here comes the new PR, since the last one got messed up!
You mentioned how it is better to get stuff that is a clear win in first, and then do the rest -> all good with me, and I am also ok on modifying this PR and dropping what is needed in order to get it in, I think regardless of exact shaping of words and similar, the value it brings is about the same and big, so that is my focus.
I will be gone for the next 2 weeks for a trip so I won't be able to work on this, but feel free to modify and add to it as needed.
@soupi and @lsmor are also very knowledgeable about the effort and can help finalize it without me, if needed.
NOTE: I haven't tested this PR! I normally do it by running
./buildAndWatch cabalbut now it got stuck on building pandoc and is not finishing, and I don't have time to wait for it so will just leave it like this as a starting point and we can work from here.Also, @tomjaguarpaw I removed that strong anti-recommendation from the downloads page that you commented on.