Redesign the haskell.org/cabal website

[23Skidoo]

Our website hasn't really been substantially updated since ~2008 and is in a dire need of a facelift. We don't need anything super advanced, just a simple static page (I'd use Hakyll) with a clean design and a news/RSS feed.

A wishlist of items we'd like to see on the new web site:

• Intro page with a brief overview of what Cabal is focusing on the cabal-install tool.
• News/feed blog with an RSS feed where we can post updates. Updates should also be visible on the front page.
• User manual link (both stable and the nightly version at http://cabal.readthedocs.io/en/latest/).
• Developer/new contributor section (how to contribute/communicate, coding standards, etc. - most of that info is in the top-level README, so you can just point there).
• Download area plus a button on the front page. Would be nice (but not necessary) if it checked the user's OS and suggested the appropriate binary or source download.
• Updated versions of existing material (FAQ/tutorials on Haskell.org wiki).

@christiantakle, if you're still interested in working on this, I'll assign this ticket to you. If anyone else is willing to help, leave a comment here and I'll give you access to the haskell/cabal-website repo.

[arianvp]

I'd be happy to invest some of my time into this.

[23Skidoo]

@arianvp Great! I'm assigning this ticket to you and @christiantakle, who also expressed interest.

[arianvp]

@christiantakle are you on #hackage in freenode? Then we can discuss this some time soon. My nick is the same on IRC

[christiantakle]

@arianvp yes Im on #hackage as takle

[christiantakle]

@23Skidoo Yes I'm still interested in working on this. I just had a busy week.

[gbaz]

As an interim measure, it would be good to just link the new docs at least. I just showed the new docs (and new-build) to folks at hac-phi and it would have been nice to have had the link to those docs from the homepage...

[23Skidoo]

@gbaz I can't access haskell.org/cabal right now (the key is on a machine in storage in another country, and I forgot to copy it when moving). If we can sort this out (revoke old permissions, grant access to a new key), then sure. Also probably makes sense to give access to @arianvp and @christiantakle while we're at it.

[23Skidoo]

@arianvp You now have write access to the haskell/cabal-website repo.

[gbaz]

@arianvp @christiantakle @23Skidoo are your github keys current (e.g. from https://github.com/23Skidoo.keys) ? I can add them all right now...

[23Skidoo]

@gbaz Just updated mine, so now it's current.

[gbaz]

Ok, added you.

[christiantakle]

@gbaz My key is current

[gbaz]

ok, you have access to sftp [email protected] as well

[arianvp]

https://github.com/arianvp.keys are current

[23Skidoo]

@gbaz Thanks! Just confirming that it works.

[23Skidoo]

@gbaz

As an interim measure, it would be good to just link the new docs at least. I just showed the new docs (and new-build) to folks at hac-phi and it would have been nice to have had the link to those docs from the homepage...

Done.

[gbaz]

Did anything come of the redesign?

Also I note the users guide at https://www.haskell.org/cabal/users-guide/ is still 1.24. Do we want to put a copy of the 2.0 guide there? Or should we just always link to the readthedocs.io site? I see there can be different versions hosted there. Could we host a stable 2.0 version there?

[23Skidoo]

@gbaz Thanks for the heads-up, I'll update that link once I'm back from vacation on Monday.

https://www.haskell.org/cabal/release/cabal-2.0.0.2/doc/users-guide/ has current docs.

[23Skidoo]

@gbaz

Did anything come of the redesign?

I am not aware of any progress. Which means that I'll probably have to do it myself.

[christiantakle]

@23Skidoo Hey sorry for the radio silence. It kinda died for me when I was trying to coordinate with @arianvp

I can pick this up again unless you already started on it.

If you have have something that you would like to see just drop some images here.

[23Skidoo]

@christiantakle @arianvp Feel free to work on this, no one else has expressed interest.

[Blaisorblade]

Also I note the users guide at https://www.haskell.org/cabal/users-guide/ is still 1.24. Do we want to put a copy of the 2.0 guide there? Or should we just always link to the readthedocs.io site? I see there can be different versions hosted there. Could we host a stable 2.0 version there?

@gbaz Thanks for the heads-up, I'll update that link once I'm back from vacation on Monday.

https://www.haskell.org/cabal/release/cabal-2.0.0.2/doc/users-guide/ has current docs.

Right now the only link is to "User's Guide (HEAD)" — I'd avoid clicking on that. Would a PR to change that link help (just found https://github.com/haskell/cabal-website/)?

I realize doing a complete redesign is a big and challenging task, but linking or copy-pasting @23Skidoo's http://coldwa.st/e/blog/2017-09-09-Cabal-2-0.html would be faster. #4807 is about linking to it in GitHub's release notes.

Similar ad-interim changes might improve the situation, as long as someone can't commit to a full redesign (which I'd guess takes no less than 1 week full-time, if not more?).

[fgaz]

@christiantakle

Not sure I follow can you give me a link to an example? I'm sure its easy to add.

https://cabal.readthedocs.io/en/latest/intro.html#a-tool-for-working-with-packages

https://hackage.haskell.org/package/base-4.11.1.0/docs/Control-Monad.html#g:2 (the whole header here)

https://docs.python.org/3/library/enum.html#using-automatic-values

So change Documentation to a subpage with the above links?
yup

hackage

I meant the #hackage irc channel (#cabal is a bit dead). But adding the hackage/package/cabal link too is a good idea

Btw, these are only my personal opinions as I am not an @haskell member. You should ask @23Skidoo or others too

[23Skidoo]

@christiantakle I think that @fgaz's suggestions make sense. Some additional comments:

• I'd make the "Download" button more prominent, like in @ciez's version.
• "Cabal" in the top left corner should be replaced with the logo, like in @ciez's version. Though I'd use the one with the light background.
• I'd add a top-level "fork me on GitHub" ribbon, or maybe a GitHub logo button like on https://www.scala-sbt.org/.
• It doesn't look like there's an RSS feed, we need it to connect the news feed to Planet Haskell.
• Each news post should have Disqus comments attached, like I have here, for example.
• I'd make the "proudly generated by Hakyll" string smaller, it's too eye-catching right now. Maybe put it under a thin <hr>, like Contact/API/About/... section in the bottom of this GitHub page.
• "Posts" and "Blog" should be "News". "Archives" should be "News Archives".
• "Quick Links" shouldn't be the main thing on the front page, we have the top menu for this. Instead in this place there should be a short intro text with a simple example of usage and links to the quick start page and further documentation instructions. See https://gulpjs.com/ and https://gruntjs.com/ for inspiration. News section can stay where it is.

@christiantakle @ciez @arianvp I gave you all write access to the haskell/cabal-website repo, maybe if @christiantakle pushed his code to an orphan branch there, you could use that repo to collaborate?

[23Skidoo]

@fgaz

Btw, these are only my personal opinions as I am not an @haskell member.

I don't think that membership of the @haskell org confers any special status on a Cabal contributor. I think @hvr can make you a member, though.

[ciez]

Any thoughts re: running 2 versions of the website: 1) static html without Js altogether and 2) with Js enabled? There seem to be 2+ contributors, each ready to look after their version.

BTW my version has RSS feed reader & formatter. The Haskell Cabal RSS feed section on the main page is gen'ed in browser.

We could store / update 1 version of up to date content as RSS XML file. Each version (html, js) would then transform the content (html: server side, js: client side) and display it without the need for maintainer / contributor to dig with each update, into the source code.

?

[quasicomputational]

-1. Which would be the canonical homepage? Why duplicate the effort and build a more complicated system? We want a no-JS version anyway for grumps like me who'd complain about having to enable JS just to find a link to the docs, so let's go with that.

[ciez]

Are the no-Js grumps - the primary target audience for the website? Or shall we try to improve UI to try to leave good impression with visitors who are curious about Haskell Cabal? It may be worth to collect stats about visitors with/out Js enabled.

Between
a) A is keen to do x1, B is keen to do x2
b) we need Y who will do y1. Anyone?

a) seems to make more sense even if x1+x2 > y1

re: disabling Js:

• Edge does not make it easy to disable Js. This may not be a feature commonly used.
• in Chrome at least it is possible to add exception to enable Js for specific websites (haskell.org?)

[23Skidoo]

Having two versions of the website sounds like overkill, however I think JS could be appropriate in a couple of places (provided that the functionality degrades gracefully in a no-JS setting):

• On mobile, making the top menu pop up when the user presses a floating menu icon (instead of having the menu displayed on top of the page) would look nicer and more compact.
• The download page could auto-detect the user's arch and OS and automatically recommend the most appropriate binary for download.

@ciez BTW, if you're not familiar with how Hakyll works, you basically write all content in Markdown, then it generates a website for you using the HTML templates you write separately.

What's important for me here is that all content should come from a single source, i.e. if there are two versions of the website, I as an author should only be required to edit a single Markdown file to publish a new blog post.

[ciez]

Must the single source be in markdown format?

What about RSS files? Can all editable content come from RSS feed? If yes, then both versions could display the same content.

[ciez]

Re: double work.

Not sure about the static html / Hakyll version. Can't vouch for others.

For me significant modifications (up to full rewrite) to React site are way easier and faster to do than with any other framework - including plain html + css.

Using material library necessitates only minor tweaks to css. Default CSS comes with the library.

[christiantakle]

It should be simple enough to add rss/atom to a Hakyll produced site. In the case of being more fancy I would properly investigate one of the many static site generators that uses react as the template language.

https://www.staticgen.com/ e.g. next.js

That should reduce duplication in theory but not sure if its needed. I think even a basic update would be a win currently.

[23Skidoo]

Must the single source be in markdown format?

Hakyll also seems to support .rst and other input formats; ReST is probably better actually, since that's what the Cabal manual is written in (it uses Sphinx). Re: RSS, it can be generated from the same Markdown/ReST source.

[ciez]

even a basic update would be a win currently.

Yes, it is so.

Well, everyone has their preferences.

With React, significant changes are easier, if I worked on them.

The React version is ready. Don't quite follow what the duplication refers to. Deploying 2 versions?

Even if one version is not maintained, it can be dropped later. Html site does not need to be modified because of the js version.

[ciez]

Re: RSS, it can be generated from the same Markdown/ReST source.

Are such RSS files already available somewhere?

Their format may be changed later. It is easy enough to adapt the code to display the content.

[ciez]

static site generators that uses react as the template language.

Are there any stats, how many visitors disable Js? Over 10%?

For very few visitors without Js and search robots we may do up a really basic html with barely any css.

Page organisation and navigation is still a bit confusing. Maybe let's revisit the content first.

[tom-bop]

Mainly for bus factor reasons, I'd also favor a simple Hakyll-based site. Gracefully handling non-JS is good to have also.

[christiantakle]

@christiantakle @ciez @arianvp I gave you all write access to the haskell/cabal-website repo, maybe if @christiantakle pushed his code to an orphan branch there, you could use that repo to collaborate?

Its been there for a while.
https://github.com/haskell/cabal-website/commits/feature/next

I will look at adding the changes proposed during the weekend. Others are welcome to play with the branch as well.

[m-renaud]

Any update on this? I've thrown together a simple restyle and content re-organization that you can browse at https://www.m-renaud.com/sites/haskell-org/cabal/ (not all the relative links work, I only updated the pages that are in the same directory/styled using the same css).

I like the idea of completely re-doing the site but this is a simple stop-gap until all the issued discussed above can be worked out. What are everyone's thoughts?

[m-renaud]

Forgot to mention, the updated html and css can be found at https://github.com/m-renaud/m-renaud.github.io/tree/master/sites/haskell-org/cabal, anyone should be able to copy/paste that into the repo the site is served from. No js or any other fanciness added.

[simonmichael]

Just found this issue - I think https://haskell.org/cabal has been using @m-renaud's redesign for some time, correct ? [+ links to the excellent readthedocs-based user guide]

It seems this initiative didn't reach completion, and Hakyll adds a bunch of complexity. I propose this issue should be closed.

[jneira]

Issues and new works can be discussed in haskell-infra repo itself, so I would open them there

[gbaz]

following above advice i think we should close this