tutorial (or manual) for haskell

[ketzacoatl]

For a person new to Haskell, the www.haskell.org website is the main "face" for Haskell as a language/tool, and community. As someone who isn't familiar with Haskell's overly-complicated community/leadership structure, you would see the haskell.org website as the authoritative source for all things blessed by the Haskell community leadership. For example, if I don't know how to learn haskell, I would naturally think, "I'll go look for their 'getting started guide', probably haskell.org/learn or some such". But if you actually look, you'll find https://www.haskell.org/documentation/ to be not very helpful for a newb (there are numerous reasons).

A seasoned haskeller would probably object:

"but that page lists all the best tutorials from around the community! It's great!"

Ok, sure, that's nice, but the seasoned Haskeller has forgotten what it's like to be new to learning haskell and to know virtually nothing about the complicated nature of the community. The big list of links is unhelpful in that it isn't specific. When I look at this list, I cannot choose which to invest myself in, and I see no means for making that decision (there is no call to action or aid to help me understand which choice would be better for me).

For example, let's compare that to rust and julia:

Rust has - https://www.rust-lang.org/learn - which links to 3 materials:

• https://doc.rust-lang.org/book/
• https://github.com/rust-lang/rustlings/
• https://doc.rust-lang.org/stable/rust-by-example/

One is a tutorial-repo on GitHub, the other two are comprehensive books. All are obviously authoritative, and iterated on by the larger community. Perhaps most importantly, in contrast to haskell's documentation page, Rust's learn page has a very clear call to action for the user, and I would feel pretty confident when making my selection.

As an additional point of comparison, Julia's "documentation" link sends us to https://docs.julialang.org/en/v1/ - also a comprehensive, authoritative book.

Another note: An intrepid newb will eventually land on the haskell wiki when looking for answers to various "topics", and given the weight that site has in the search engine, but yet unmaintained content, the wiki pages are often near the top of search results and rather embarrassing when read in detail.

Thus, I propose haskell.org host and maintain an authoritative manual/document for Haskell, one suitable for new Haskellers, one that shows them how to get up and running, and one that is available to be maintained by the community.

[TikhonJelvis]

I think this is a great suggestion. We've talked about doing something like this as a committee before, in large part inspired by Rust's website.

A project like this would need community support (to source and write the actual materials, integrate it into the site... etc) and somebody to lead/organize the effort. This seems like the kind of effort the Haskell Foundation might support, so there should be concrete action around this once they get fully operational.

In the meantime, if you have a specific idea for what this could look like or how the project could be organized, you could write up a concrete proposal as a way to discuss the idea and gather some community involvement. The Haskell.org proposal process is modeled on the GHC proposals process but it's very new and doesn't have an existing audience, so a proposal like this would need some marketing to get community attention. I'd be happy to help with that if you're interested in writing something up.

[ketzacoatl]

Yea, haven't there been better write-ups already authored on this topic? (at least better than what I have to offer) we should probably just look those all up.

[TikhonJelvis]

There are a lot of existing materials, but it would take some work to curate good options, coordinate with authors and combine them into a single coherent and up-to-date reference.

That may or may not involve writing content from scratch, but it will definitely involve community work and organization. I wasn't suggesting writing tutorials; rather, I was suggesting a proposal that would outline the project as a whole: laying out the goals (how would we know whether we're doing a good job?), defining how to source and accept contributions, figuring out how to resolve potentially controversial editorial questions... etc.

This will overlap with concrete work the Haskell Foundation wants to support. I'm not sure if they've started on anything yet—still early stages for the Foundation—but we definitely want to work closely on community projects like this.

I have some general ideas about how this could work, and I'm happy to either write a proposal myself (a couple of months from now at the earliest though) or help you with a proposal if that's something you're interested in working on. A good start is probably taking a look at how other communities—Rust, Elixir, anyone else?—have approached this.

I would expect this proposal to be a conversation-starter—for the Haskell.org Committee, the Haskell Foundation and the rest of the community—more than anything else. This means the project won't move fast at first, but I think that's inevitable for any effort that we want to represent the community holistically.

[ketzacoatl]

@TikhonJelvis, thank you for the reply, and apologies for the delay in my response.

I wasn't suggesting writing tutorials; rather, I was suggesting a proposal that would outline the project as a whole: laying out the goals (how would we know whether we're doing a good job?), defining how to source and accept contributions, figuring out how to resolve potentially controversial editorial questions... etc.

Yes, I understand, I was speaking to the proposal as well - I don't think it should be on a rando-haskeller like me (and I believe plenty of other rando-haskellers have made similar proposals already!), I believe facilitating and leading that project is the responsibility of the haskell.org committee.

That said, I contributed my two-cents here https://discourse.haskell.org/t/rfc-documentation-overhaul-on-haskell-org/1942/8.

[TikhonJelvis]

I don't think it should be on a rando-haskeller like me (and I believe plenty of other rando-haskellers have made similar proposals already!), I believe facilitating and leading that project is the responsibility of the haskell.org committee.

Don't sell yourself short :). Just being active in the community makes you more than suitable for leading something like this.

As it happens, we have talked on the Haskell.org committee about organizing something like this, but we haven't gotten past the "wouldn't it be nice" stage. I'm sure we'll get there eventually, but there's a practical limit to what people have the time and attention to do, so these things can move slowly. Sometimes the best way to speed it up is to jump in and give the community a push; I'm sure the committee would be happy to help get something like that onto the website itself in that scenario.

[ketzacoatl]

As it happens, we have talked on the Haskell.org committee about organizing something like this, but we haven't gotten past the "wouldn't it be nice" stage. I'm sure we'll get there eventually, but there's a practical limit to what people have the time and attention to do, so these things can move slowly. Sometimes the best way to speed it up is to jump in and give the community a push; I'm sure the committee would be happy to help get something like that onto the website itself in that scenario.

Thanks for the push @TikhonJelvis, though I am not going to go out on a limb and do all that work without some agreements on direction/requirements/goals/etc. So if the committee is looking for volunteers to step up, it would really help if the committee took a few small steps:

• Define goals for the manual
• Define an example table of contents
• Link to some existing doc content from the community for which this manual should seek inspiration

Also, sites like the defunct haskell-lang.org demonstrate that there are strong opinions and lack of consensus on the details for what this manual should look like. I think the committee should take a leadership role in making this happen, possibly also with the assistance and support of the Haskell Foundation.

[tomjaguarpaw]

it would really help if the committee took a few small steps

• Define goals for the manual
• Define an example table of contents
• Link to some existing doc content from the community for which this manual should seek inspiration

I doubt the Haskell.org committee has the bandwidth to do even that, unfortunately. It barely has the bandwidth to approve small PRs to this repo. I suggest that

1. anyone who wants to write such a tutorial writes one
2. they host it somewhere else
3. after it is demonstrated that the community loves it, the committee agrees to host it on Haskell.org

2 need not actually occur for 3 to occur, but I include it because it seems easier for 3 to occur after 2 and as a way of avoiding wasted work if 3 does not subsequently occur.

Regarding the website, I think it is probably best to see the Haskell.org committee neither as leaders nor workers, but rather as gatekeepers[1] who incorporate work performed by others, enforce a minimum standard, and try to reflect broad community opinion.[2]

Case in point: the creation of ghcup was neither instigated nor led by the Haskell.org committee. That achievement fell to an individual community member who diagnosed a need in the community and developed a solution. Once that solution became best practice it was incorporated into the Haskell.org website. I suggest a similar course of action for developing "an authoritative manual/document for Haskell".

[1] "gatekeeper" has taken on a negative connotation in recent online discourse, but I intend this usage in a positive way.
[2] This is how things seem to me, a committee member. My fellow committee members may disagree.

[ketzacoatl]

I doubt the Haskell.org committee has the bandwidth to do even that, unfortunately. It barely has the bandwidth to approve small PRs to this repo.

Ok, you would know better than me.

I suggested the committee define goals as a way to help volunteers get a clear scope of what the committee thinks would be appropriate or a reasonable fit on haskell.org.

anyone who wants to write such a tutorial writes one
they host it somewhere else
after it is demonstrated that the community loves it, the committee agrees to host it on Haskell.org

While I agree there's a time and place for that course of action, I didn't think it was the best course of action here. IMHO, I think it would be better to produce an authoritative, community-driven "how to haskell" guide, and for that to live on haskell.org. It should be opinionated and provide guidance as an onboarding experience. Written from the beginning, to go on haskell.org.

Regarding the website, I think it is probably best to see the Haskell.org committee neither as leaders nor workers, but rather as gatekeepers[1] who incorporate work performed by others, enforce a minimum standard, and try to reflect broad community opinion.[2]

The committee's role as a gatekeeper as you described is one of the reasons why I suggested the committee define goals, or scoping out what is reasonable to host on haskell.org.

[tomjaguarpaw]

I suggested the committee define goals as a way to help volunteers get a clear scope of what the committee thinks would be appropriate or a reasonable fit on haskell.org.

The committee's role as a gatekeeper as you described is one of the reasons why I suggested the committee define goals, or scoping out what is reasonable to host on haskell.org.

I agree that in an ideal world the committee (or someone to whom the task is delegated) would do this. In the actual world, we simply don't have the resources. Anyone who wants to volunteer their time improving the haskell.org site has to fight tooth and nail to be allowed to! That's not good but it is the reality. (The same goes for many other parts of the ecosystem.) The upside is that if one is willing to do that tooth-and-nail fighting they will likely be successful (but it's a lot of effort as I know from personal experience).

Any suggestions about improving this status quo will be gratefully received.

[ketzacoatl]

I agree that in an ideal world the committee (or someone to whom the task is delegated) would do this. In the actual world, we simply don't have the resources.

I can understand, though I was hoping the committee would be willing to define what they consider acceptable targets or reasonable scope for changes or the type of content on haskell.org. ce-la-vie

Anyone who wants to volunteer their time improving the haskell.org site has to fight tooth and nail to be allowed to! That's not good but it is the reality. (The same goes for many other parts of the ecosystem.)

This is beyond unfortunate, not to mention inefficient on the whole and totally demoralizing for contributors for whom we should be really thankful and not overburden to the point of burnout.

[tomjaguarpaw]

I was hoping the committee would be willing to define what they consider acceptable targets or reasonable scope for changes or the type of content on haskell.org

To give more colour to my earlier comment, "defining acceptable targets or reasonable scope for changes" is most of the work of getting the changes done.

Hacking on Hakyll build rules, tweaking CSS and page layouts etc. is technical work but limited in complexity and the community is replete with people who can perform such work. Even though writing content is challenging and takes time it's not the difficult part.

The difficult part is working out what should be done and, specifically, building consensus within the community that it should be done. The vast, vast majority of the work involved in my putting together #194 was noticing that distro-specific installation instructions were becoming out of date and probably unhelpful, determining that one good course of action was to source community volunteers for owning them (because such ownership is a clearly defined role with limited scope), filing #170 to bring the issue to the attention of the committee and the community, facilitating the community discussion as per #170 (comment), and collating the feedback. As grateful as I am to hasufell for initiating the PR, I wager the parts above were 10x more time consuming and emotionally draining than writing the changes.

So, I appreciate your eagerness to spend your time and energy contributing to the Haskell ecosystem, and I appreciate you wanting to unlock the untapped enthusiasm of other members of the community. I do too! But it's not really possible to reduce the burden on the committee by first asking it to "define acceptable targets or reasonable scope for changes" because doing so is the burden!

Instead what we need are leaders who are willing to sink hours or days of work into an effort that they consider valuable without having a prior guarantee that their work won't be wasted, because, I'm sorry, it's just not possible to give such a guarantee now. What I can guarantee though is that if someone assumes such a role I personally will support them as much as I can by clarifying processes, advocating for them, and all sorts of other similar "managerial" work.

In short, the recipe is not:

1. Ask those in authority what the problem is
2. Ask those in authority what the solution is
3. Implement the solution
4. Deploy the solution

The recipe is:

1. Spot a problem
2. Devise a solution, alone or in a group
3. Implement the solution
4. Advocate very, very hard for the solution in order to build community consensus that the solution should be implemented.
5. Deploy the solution

(The order of 3 and 4 may be switched but I think success is more likely in the order I wrote them.)