Tutorial from the 2000's is off-putting

[Kleidukos]

As seen in a beginners community space:

I wanted to learn something about haskell so I googled it, saw the first result was an tutorial from haskell.org, clicked on it, saw that it was text spanning 100% viewport width with zero styling, and noped out of there immedatiely[sic] to find a different site. Someone should tell the org that the state of their docs website is embarrassing and bad for adoption.

The tutorial in question is https://www.haskell.org/tutorial/io.html.

We should really think about decommissioning this tutorial, which is 25 years out of date.

[gbaz]

We should not decommission classic writing on haskell, especially by one of the original authors of the language. This in particular was the writing on Haskell which a whole first generation of Haskellers learned from, and despite being in some respects out of date its a model of clarity and exposition. We can add something to the main page to indicate that it is older, and if someone wants to adopt it, we can improve formatting.

(In fact, outside of the applicative hierarchy, this tutorial is not really out of date, because it covers Haskell 98's core language, which still exists at the heart of current day Haskell)

[PPKFS]

We should not decommission classic writing on haskell, especially by one of the original authors of the language.

that's not what is being said, by the original author or by Hecate. It should be decomissioned as a tutorial. This is absolutely not something that should be coming up high in searches in 2025 with the URL implying it's the go-to official IO tutorial.

[Kleidukos]

@gbaz I agree with you on its historical value but I can't say I have the same emotional bond to it, since I learned Haskell ten years ago. Moreover, during my own school years I have not seen any manual from 2000, as the ways of explaining things change with their time.

This text can be absolutely improved, as the main criticism that I have read is on its typesetting. Just to take an example from that very same page:

ready                   :: IO Bool
ready                   =  do c <- getChar
                              c == 'y'  -- Bad!!!

I beg your pardon but 19 spaces between the identifier and the start of its type signature and definition is just ridiculous. It's inconsistent within this page and gives that style a form of legitimacy that is completely unwarranted.

[gbaz]

what does it mean "decomissioned as a tutorial"? i suggested we add a comment to its main page that notes that it is rather old.

Also if someone wants to modernize the typesetting, I think that would be fine too...

As is, I think that the typesetting effectively indicated that this was very old, and the person then went and googled something newer -- which is fine. In fact, it is not the top result for either "haskell tutorial" or "haskell introduction" though it does appear on the first page of both results. The first result in both cases is LYAH. Further, the google preview text says "The Haskell language has evolved significantly since its birth in 1987. This tutorial deals with Haskell 98" -- which I would think would tip people off that the tutorial is for Haskell circa 1998.

I.e. the page, from anecdotal and investigatory evidence seems to signal quite well it is old already.

[Kleidukos]

This page is in fact well-ranked for the search query that leads to it. No doubt being hosted on haskell.org impacts its ranking significantly.

[tomjaguarpaw]

@gbaz Are you saying you want this documentation to continue to be hosted under the www.haskell.org domain? Or would you be happy if it were preserved by moving it to some other domain?

(Certainly I think that in 2025 most people would expect that a tutorial hosted under www.<language>.org to be a "good current tutorial" for "Language".)

[gbaz]

Our mandate has basically always been to preserve the urls as they exist, or to preserve at least redirects. We don't want any broken links to result from changes made -- especially to historic documents and reference material. Preventing linkrot is a sort of core responsibility of web presence.

I again repeat my proposal that we add a comment to the main page noting it is rather old.

Again, I also ask, typesetting aside, is there a reason that this is not a good current article on the haskell language?

[L0neGamer]

As the first result for haskell tutorial IO, here are the things that I don't think should be explained as a newcomer's first entry into IO in Haskell:
exception handling with IOError
files, channels, handles
lazy IO with regards to file reading

But if we are allowed to mention the typesetting, this page is very easy to bounce off of if you're not committed to trying to understand Haskell; it's unpleasant to look at and hard to understand without some styling to neaten it up.

Personally, I'd be fine if the tutorial got a touch up and was brought 25 years up to date (along with the rest of A Gentle Introduction to Haskell, of which this is a small part), but we would still need to decommission the original to take advantage of the seemingly high SEO tutorials we didn't know about.

(On trying to research John Peterson, who seemed to be the last owner of AGItH, I found this reddit post about his death, which is sad. edkmett said at the time that John was one of the authors of the Gentle Introduction to Haskell, which many of us remember as anything but gentle)

[gbaz]

Sounds like we want a volunteer to improve the typesetting!

[jmct]

It's very clear there are a few distinct issues here:

1. The aesthetics of the tutorial being off-putting to 2025 internet sensibilities (I agree)
2. The value of the content in "A Gentle Introduction to Haskell" (I think very high)
3. The willingness to adapt either of the above

I think it's very clear that a high-ranking tutorial for Haskell should look good, I don't think it would take much, i.e. the same as http://bettermotherfuckingwebsite.com/ would do wonders.

I personally believe that "A Gentle Introduction to Haskell" is one of the better ways to learn basic Haskell. There may be some small updates required, which leads me to...

Why don't we just make those small updates? Paul was a very reasonable man, and very accommodating! In fact, on the main page it says the following:

Premission [sic] is granted to correct, improve, or enhance this document

Let's not throw out the baby with the bathwater here, his prose and explanations are fantastic, let's keep them.

My proposal: Let's update this with the minimal changes required, we can keep an archived version and point to it if we'd like (I think we should).

[jmct]

Since both Paul and John have passed away, I've reached out to Joseph about it.

(very biblical names, btw)

[L0neGamer]

Sure! Let's decommission this version of this and create a new one based off of it.

Maybe we can even put a call to the discourse if anyone wants to take a stab at it.

[tomjaguarpaw]

Our mandate has basically always been to preserve the urls as they exist, or to preserve at least redirects. We don't want any broken links to result from changes made -- especially to historic documents and reference material. Preventing linkrot is a sort of core responsibility of web presence.

A venerable and respectable policy, discussed at Cool URIs don't change (as well as probably many other places). There's a big difference between preserving the URLs and preserving redirects. Would you be content if we hosted this tutorial off www.haskell.org but put redirects in place from the original URLs?

[gbaz]

Let's not worry about where the tutorial lives for now. If the redirect is preserved the google search ranking would be preserved, so it doesn't matter either way on that count, and anyway the places that haskell has to host things all are, naturally, haskell.org urls. In any case, its cart before the horse. We should proceed with @jmct 's suggestion and then consider further steps from there.

[tomjaguarpaw]

If the redirect is preserved the google search ranking would be preserved

That's surprising to hear! Do you have any references where I could learn more about how search engines index redirects. (There must be some complexities: For example, I doubt I can redirect to popular Wikipedia pages from my site and obtain Wikipedia-levels of ranking.)