[RFC] Documentation overhaul on haskell.org

#1

Following the conversation from the neighboring thread (“Forming a technical agenda” for the Foundation), some people have floated the wish for better/more focused documentation in various parts of haskell.org .

I took a fresh look today and indeed there are some gaps that the Haskell Foundation could issue a call for, prioritize and follow up to completion. They don’t even need to be written from scratch, many are already online, but some curation and a blessing from being on our homepage would go a long way.

For example, focusing on the tutorials part , I think we are still missing one or a few project-oriented, end-to-end approach at learning the language. For example: “build a web application”.

image
image946×1060 91.8 KB

Rust instead has a dedicated section and three whole books on distinct application styles, linked from their “learn” page https://www.rust-lang.org/learn :

image
image2192×694 53.7 KB

Or Elm ! https://elm-lang.org/examples Complete with in-browser playground:

image
image1134×756 36.6 KB

I will summon @gilmi because I think their tutorials are pretty spot on this , e.g. “Build a bulletin board using scotty and friends” : https://gilmi.me/blog/post/2020/12/05/scotty-bulletin-board , but there are many outstanding examples by now.

8 Likes
#2

Other examples of possible “overhauls”:

  • Some visual prioritization of the content. This requires a little design thinking AND some Haskell knowledge. Many modern programming languages websites (Elm, Rust …) help the reader with very clear visual cues.
  • Content prioritization : separate “overview”/“exhaustive”/“applied” documentation material. I mean that a number of those resources are technically correct but they tend to overwhelm the reader with detail , listing feature after feature of the language but providing a very slow start for the Working Programmer.
  • Speaking of web programming, also the Haskell Wiki needs some serious love. I’m sure this is another topic that’s periodically floated but not exactly high on the todo list. For example we find this nice but somewhat dated article https://wiki.haskell.org/Web/Literature/Practical_web_programming_in_Haskell that mentions CGI (“and FastCGI” !) , which is most definitely not how web apps are built nowadays. And we can rapidly find many more wiki pages that would deserve either some curation or to be archived.

Looking forward to start a discussion on these and related things.

7 Likes
#3

Other ideas :

3 Likes
#4

Excellent thread. Re:

For the time being we are lucky enough to have a CIS194 which is:

  • extremely well done; and
  • free.

and that in my opinion should be listed prominently on top.

If there is some consensus on which direction to take, I can write a patch!

#5

Thank you for the shout out @ocramz, I really appreciate it :slight_smile:

I also think that the haskell.org website really really needs some work. The Downloads, Documentation and Community pages can be improved a lot imo.

For the downloads page, there’s just too much information for someone that is not yet familiar with Haskell. The page should, in my opinion, make the decision for the user on which solution to use. the ghcup page does a pretty good job at this - just run this and you have Haskell installed. It’s also very good to a have a link for more information, but I think the main downloads page has to be simpler or people will get lost.

The other two pages, Documentation and Communities, are just a partial dump of information organized as unordered lists. How would I, as a newcomer, pick a good tutorial from this list? Maybe there needs to be a few blessed resources for different types of students (as there are many people coming to Haskell to achieve different things), including some information to why one should pick said resource, and maybe the other resources could be split into categories? Picking the wrong resource is an easy way to get frustrated and give up, so maybe more care should be given to this section as well.

3 Likes
#6

Both haskell.org and Wiki require a massive redesign in order to achieve such goals:

  • Provide a modern image of Haskell
  • Allow for easy navigation across the modern Haskell world
  • Enable an easy enter for newcomers
  • Provide a view on how to use Haskell for real production for everyone interested
  • Provide a view on a scientific Haskell side (this one should have a lower priority than it’s now - edited)

Currently, these resources contain a lot of unneeded and obsolete information, they are disorganized, unobvious and quite inconvenient to use. It’s like your 30 years garage where you store everything not used at home.

I personally can contribute into helping with materials of production Haskell. In particular, I have this list of materials on Software Design in Haskell. I believe it’s much more helpful because it’s focused and well-structured.

I would also ask to add my book into the Books page.

I don’t see books by Maguire and Parsons there as well.

2 Likes
#7

Please feel free to add your book to the wiki. We don’t have the Wikipedia’s NPOV (neutral point-of-view) fetish.

#8
  • Drop the wiki completely - it’s actively unhelpful, and any of us can all publish whatever we want here on discourse, or on github/gitlab/etc elsewhere.
  • Replace the wiki with a complete, and authoritative guide for getting things done in haskell. It should be
    • targeting new haskellers
    • focused on their onboarding experience (what % converted to “competent and capable haskeller”)
    • carrying them through to intermediate and then beginner-advanced levels
    • opinionated, focused on reliable/proven best-practices
    • inclusive and acknowledge places where alternatives exist
    • extensive in topics, covering all the typical scenarios seen in hobby and commercial products
    • maintained by the community
    • based on and using existing material and prior-art, including for example rust’s, Stephen’s “what I wish I knew”, the retired haskell-lang.org site, etc.
  • Make the downloads page stupid-obvious: When a pythonista/PHP/gopher says “I’m going to try haskell”, and goes to haskell . org / downloads for the first time, they should not get stuck/blocked wondering what to do, they should have clear and obvious instructions for their next steps (downloading, and getting started on into docs and code examples, etc).
  • Keep available the curated list of tutorials and books/docs/etc - the existing list of tutorials/docs/books is great and should continue to exist, but it needs a new place next to the authoritative guide described above.

Just echoing what I’ve heard others say that I believe makes sense and addresses the problems we have picking up and being efficient with Haskell.

3 Likes
#9

Hi @hgolden, can you please hint me how to do that? I tried to find a way to get an account there, but failed.

#10

@ketzacoatl

gabriel’s “what I wish I knew”

Maybe you meant Stephen Diehl’s “What I wish I knew when learning Haskell”?

#11

Hi @graninas, it is a simplified adventure game: :slightly_smiling_face:

NOTE: Automatic wiki account creation has been disabled. If you would like an account please email “wiki-account-request” (at the domain haskell dot org) or, if you find that unresponsive, on the haskell-cafe mailing list.

In the email state your preferred username for the wiki. (Use Special:Listusers to check if the username is available). A wiki admin will then create an account for you and a temporary password will then be sent to your email address.

#12

@hgolden Okay, I see, thanks.

@here, may I express an opinion that in the Haskell world, it’s too many systems which require to ask someone to grant something? That’s a huge obstacle for improvements, and in general feels like an unnecessary gatekeeping (no matter what it really is).

I would propose to not only make the systems more open and friendly, but also bring more trust to the community in general.

4 Likes
#13

I very much welcome the idea of improving the Haskell documentation platforms, and I too believe that Wikis are untenable because they make it impossible to gauge the degree to which the information presented is official and up-to-date.

However I don’t think Rust is the best student in the class as far as docs. To me this role is currently occupied by Python. Our Pythonic friends have managed to pull off a very clear, rigorous, exhaustive, and easy to browse documentation platform. And the best of all: every version of the language is respected.

I don’t see any reason not to mimick them in all regards, except for a few areas where we might want to diverge:

  • we not only have “standards” (i.e. Haskell 2010) but also compiler versions
  • the type system might need a suite of introductory material of its own, tightly integrated with the various language pragmas, and thus cannot consist in just language references
  • as others have suggested above, it cannot harm presenting paradigmatic use cases in which Haskell excels (web apps, parsers, DSL, compilers, etc.)
  • beyond the standard libraries we could do the new users a favour and cherry-pick a set of well-maintained, performant librairies serviceable to the previous point

This is a lot of work and perhaps it would be good to set up a “task force” on this topic?

1 Like
#15

@here, may I express an opinion that in the Haskell world, it’s too many systems which require to ask someone to grant something? That’s a huge obstacle for improvements, and in general feels like an unnecessary gatekeeping (no matter what it really is).

You wouldn’t be the first to voice the opinion!

I’m still not sure where to submit a proposal to base, for replacing string with text and bytestring (I won’t even say how much time I spent looking, it’s embarrassing).

1 Like
#16

Maybe you meant Stephen Diehl’s “What I wish I knew when learning Haskell” 1?

Derp… yep, corrected, thanks!

#17

@graninas re. “asking for permission” : I agree account creation should be automated in some sensible way.

I wonder how to move this thread towards some practical outcome; @Nycticorax what timezone are you in?

#18

You make a number of very good points but I’m afraid some of these changes will encounter resistance:

  • downloads page : you wouldn’t believe the amount of bikeshedding and argument that happened when sorting the ["stack", "haskell-platform", "minimal-installers"] list years ago (plus nowadays there’s ghcup as well ?). Also, some people really liked having an extensive description of each option rather than just “click here”. Must be an aesthetics thing.
  • replacing the wiki with an authoritative guide + curated list of tutorials : I think this is really one “action item” (a rather large one though). A bunch of tutorial material is scattered over the net, whereas it should be under haskell.org . This would also require authors’ permission to copy, among other things.
#19

My time zone is UTC +1.

#20

You make a number of very good points but I’m afraid some of these changes will encounter resistance

Yea, I don’t disagree. However, I believe the value those changes bring is worth the effort.

#21

I sent in my request earlier in the week and am still waiting for access to the wiki. Did you have better luck?