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”.
Rust instead has a dedicated section and three whole books on distinct application styles, linked from their “learn” page Learn Rust - Rust Programming Language :
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.
Thank you for the shout out @ocramz, I really appreciate it
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.
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.
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.
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.
@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.
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?
@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).
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.
