New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Redesign the haskell.org/cabal website #4013

Open
23Skidoo opened this Issue Oct 21, 2016 · 56 comments

Comments

Projects
None yet
10 participants
@23Skidoo
Copy link
Member

23Skidoo commented Oct 21, 2016

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.

@23Skidoo 23Skidoo added this to the 2.2 milestone Oct 21, 2016

@arianvp

This comment has been minimized.

Copy link
Collaborator

arianvp commented Oct 21, 2016

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

@23Skidoo

This comment has been minimized.

Copy link
Member

23Skidoo commented Oct 21, 2016

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

@arianvp

This comment has been minimized.

Copy link
Collaborator

arianvp commented Oct 21, 2016

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

@christiantakle

This comment has been minimized.

Copy link
Collaborator

christiantakle commented Oct 23, 2016

@arianvp yes Im on #hackage as takle

@christiantakle

This comment has been minimized.

Copy link
Collaborator

christiantakle commented Oct 23, 2016

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

@gbaz

This comment has been minimized.

Copy link
Collaborator

gbaz commented Oct 23, 2016

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

This comment has been minimized.

Copy link
Member

23Skidoo commented Oct 23, 2016

@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

This comment has been minimized.

Copy link
Member

23Skidoo commented Oct 23, 2016

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

@gbaz

This comment has been minimized.

Copy link
Collaborator

gbaz commented Oct 23, 2016

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

@23Skidoo

This comment has been minimized.

Copy link
Member

23Skidoo commented Oct 23, 2016

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

@gbaz

This comment has been minimized.

Copy link
Collaborator

gbaz commented Oct 23, 2016

Ok, added you.

@christiantakle

This comment has been minimized.

Copy link
Collaborator

christiantakle commented Oct 24, 2016

@gbaz My key is current

@gbaz

This comment has been minimized.

Copy link
Collaborator

gbaz commented Oct 24, 2016

ok, you have access to sftp cabal-site@www-origin.haskell.org as well

@arianvp

This comment has been minimized.

Copy link
Collaborator

arianvp commented Oct 24, 2016

@23Skidoo

This comment has been minimized.

Copy link
Member

23Skidoo commented Oct 24, 2016

@gbaz Thanks! Just confirming that it works.

@23Skidoo

This comment has been minimized.

Copy link
Member

23Skidoo commented Dec 8, 2016

@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

This comment has been minimized.

Copy link
Collaborator

gbaz commented Aug 26, 2017

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

This comment has been minimized.

Copy link
Member

23Skidoo commented Aug 26, 2017

@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

This comment has been minimized.

Copy link
Member

23Skidoo commented Aug 26, 2017

@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

This comment has been minimized.

Copy link
Collaborator

christiantakle commented Aug 26, 2017

@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

This comment has been minimized.

Copy link
Member

23Skidoo commented Aug 27, 2017

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

@Blaisorblade

This comment has been minimized.

Copy link
Collaborator

Blaisorblade commented Oct 2, 2017

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?).

@ciez

This comment has been minimized.

Copy link

ciez commented Jun 17, 2018

@fgaz

If the Js version appears usable to the users with Js enabled, then it is easier to write another version of the website for the users without Js and redirect them to the html only version.

The new version can redirect no-Js users to the current version until the new html-only version is ready.

@christiantakle

This comment has been minimized.

Copy link
Collaborator

christiantakle commented Jun 17, 2018

@fgaz

This comment has been minimized.

Copy link
Collaborator

fgaz commented Jun 17, 2018

@ciez

Well, why don't we only write the non-js version then

@ciez

This comment has been minimized.

Copy link

ciez commented Jun 17, 2018

@fgaz

Fair enough. Let's wait for the html-only version.

Christian's version above seems to be html-only.

@christiantakle

This comment has been minimized.

Copy link
Collaborator

christiantakle commented Jun 17, 2018

@ciez @23Skidoo @fgaz I just need some feedback on https://christiantakle.github.io/

Its pretty simple and we can take it in any direction.

@fgaz

This comment has been minimized.

Copy link
Collaborator

fgaz commented Jun 17, 2018

@christiantakle

I like simple.

Just 3 things:

  1. I think the color scheme should be the same that https://haskell.org and https://hackage.haskell.org use
  2. Maybe add the cabal logo to the home page
  3. Maybe add those "¶" links to each header like readthedocs, hackage, the python docs and many others do
@fgaz

This comment has been minimized.

Copy link
Collaborator

fgaz commented Jun 17, 2018

@christiantakle

As for the content:

  1. I think the docs link should point to a page with at least:

    • FAQ
    • User's Guide
    • User's Guide (HEAD)
    • API
  2. In the blog page:

    Here you can find all my previous posts

    "my" should be "our", "the" or something similar

  3. Maybe add a link to the issue tracker

  4. Maybe add a link to the source

  5. Maybe to the ML too?

EDIT:
ooh, and one to the #hackage irc channel.
Maybe all the links I listed should be in a "community" page or something

@fgaz fgaz modified the milestones: 2.2, 2.4 Jun 17, 2018

@christiantakle

This comment has been minimized.

Copy link
Collaborator

christiantakle commented Jun 18, 2018

@fgaz

I think the color scheme should be the same that https://haskell.org and https://hackage.haskell.org use

I agree I allready toke elements from them. Maybe It should just be almost equal to https://www.haskell.org/downloads

Maybe add the cabal logo to the home page.

I choose not to originally since I think it could use a touch op but I can add it in there and we can see if it should be updated in a second pass.

Maybe add those "¶" links to each header like readthedocs, hackage, the python docs and many others do

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

As for the content:

I think the docs link should point to a page with at least: FAQ, User's Guide, User's Guide (HEAD), API

So change Documentation to a subpage with the above links?

In the blog page. Here you can find all my previous posts. "my" should be "our", "the" or something similar
I will change it to "our".

Maybe add a link to the

  • issue tracker
  • the source
  • ML too?
  • hackage

I will add a new top-level heading "community" with those links.

@fgaz

This comment has been minimized.

Copy link
Collaborator

fgaz commented Jun 18, 2018

@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
screenshot-2018-6-18 1 introduction cabal release user s guide

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

https://docs.python.org/3/library/enum.html#using-automatic-values
screenshot-2018-6-18 8 13 enum support for enumerations python 3 6 6rc1 documentation

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

This comment has been minimized.

Copy link
Member

23Skidoo commented Jun 19, 2018

@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

This comment has been minimized.

Copy link
Member

23Skidoo commented Jun 19, 2018

@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

This comment has been minimized.

Copy link

ciez commented Jun 19, 2018

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

This comment has been minimized.

Copy link
Collaborator

quasicomputational commented Jun 19, 2018

-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

This comment has been minimized.

Copy link

ciez commented Jun 19, 2018

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

This comment has been minimized.

Copy link
Member

23Skidoo commented Jun 19, 2018

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

This comment has been minimized.

Copy link

ciez commented Jun 19, 2018

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

This comment has been minimized.

Copy link

ciez commented Jun 19, 2018

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

This comment has been minimized.

Copy link
Collaborator

christiantakle commented Jun 19, 2018

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

This comment has been minimized.

Copy link
Member

23Skidoo commented Jun 19, 2018

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

This comment has been minimized.

Copy link

ciez commented Jun 19, 2018

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

This comment has been minimized.

Copy link

ciez commented Jun 19, 2018

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

This comment has been minimized.

Copy link

ciez commented Jun 19, 2018

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

This comment has been minimized.

Copy link

tom-bop commented Jun 19, 2018

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

@christiantakle

This comment has been minimized.

Copy link
Collaborator

christiantakle commented Jun 19, 2018

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

@23Skidoo 23Skidoo modified the milestones: 2.4, 2.4.1 Sep 17, 2018

@m-renaud

This comment has been minimized.

Copy link
Collaborator

m-renaud commented Nov 3, 2018

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

This comment has been minimized.

Copy link
Collaborator

m-renaud commented Nov 3, 2018

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment