[RFC] Documentation overhaul on haskell.org

#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!

2 Likes
#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.

4 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.

3 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.

8 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.

5 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?

2 Likes
#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?

#22

Hi @ketzacoatl, I received your request and responded to it 22 hours ago to your email address: Your desired username is already taken (It was registered in 2016). Is it possible that you already have an account? If not, please send a different username choice.

We generally respond to requests within 24 hours, often much sooner. In your case, the request went into my spam folder so it took me 18 hours to respond. Perhaps my response went into your spam folder?

I would be happy to open up self-registration, but it has quickly led to a lot of spam in the wiki. If there is a better solution available we’d be happy to try it.

1 Like
#23

Hello @hgolden, You would be correct! Thank you for reaching out to sync up! :slight_smile:

If there is a better solution available we’d be happy to try it.

IDK if it is available in the wiki software, but enabling auth through google/github/gitlab/etc seems to be a reasonable solution to this problem.

1 Like