Website needs updating

[ezyang]

This isn't really the right place, but I'm not sure where else to report this. The Haddock website: https://www.haskell.org/haddock/ needs some updating:

• Development section needs to point to GitHub
• Simon Marlow contact link should be updated to something more general

[Fuuzetsu]

This is a fine place to report this. Honestly I have considered to just get rid of that site all together. Currently it mainly serves as a host for user documentation but if we do something about #338 then we can just use GitHub for that.

[sol]

We can use GitHub pages, even if we stick with docbook. It can server arbitrary static HTML.

[gbaz]

I'll actually just fix a few things on the page for now to point to the github as the central thing, and then let people sort out the rest. But the documentation certainly should be updated and hosted somewhere!

[gbaz]

Ok, the page is now updated to point to github for all development work. Uploading new docs still needs to happen, or finding a new home for them if preferred...

[sjakobi]

Cabal and stack now use Read the Docs to serve their documentation. One feature of RtD that I find very useful is that users can easily switch between different versions of the documentation, e.g. https://docs.haskellstack.org/en/stable/README/ and https://docs.haskellstack.org/en/v1.2.0/README/.

Given that many haddock users don't use the latest version, I think that could be a useful feature. I haven't seen anything similar for GitHub Pages.

[Fuuzetsu]

I have (or at least had and could probably get it again if I don't) access to haskell.org/haddock; not sure if I can set up a redirect or something but anyway we just need someone eager to do the leg-work of porting it over to pages/readthedocs/whatever it is

[gbaz]

If anyone needs access to the site, I'll help out. Or if it just ends up being a redirect I can put it in place...

[sjakobi]

we just need someone eager to do the leg-work of porting it over to pages/readthedocs/whatever it is

I'll have some time in mid February to do that if no one beats me to it!

[sjakobi]

So, I'm kind of ready to do the porting (to Read the Docs), but I'm split about which markup language to use:

• If we go for Markdown we're limited to CommonMark which has subtle and not-so-subtle differences to GitHub flavored Markdown and e.g. doesn't support tables.

• reStructedText is the more fully featured alternative that Read the Docs recommends for technical documentation but which I believe fewer contributors will be familiar with. GHC uses RST for its user's guide.

Any opinions / preferences?

[ezyang]

+1 for RST. I don't think the unfamiliarity will be a problem, esp. since GHC and Cabal's users guides are written in RST.