Download Pages

[Anniepoo]

The fundamental problem with the existing d/l area is that it's a twisty maze of passages. So my instinct was to put everything on one page. I've now got a better mockup of that page, and it's apparent that's also going to be confusing. Too much noise! So I'm backing up and doing some design again.

A few ideas -

1. Download->SWI-Prolog links to an overview page with (windows) (mac) (linux) buttons

advantages - gives a good place to give advice to selecting best version. Disadvantage - strange little page with just 3 buttons on it, and we've conditioned our users to fear twisty passages.

1. Download->SWI-Prolog gets submenus windows, mac, linux Each goes to it's own page.

advantages - like 1, gives a good place to help select a version. Fixes 1's bouncer page issue. disadvantages - nested menus always disliked

1. Download->SWI-Prolog links to an overview page (windows32) (windows64) (mac) (linux Debian and Ubuntu) Redhat (Fedora, RHEL, CentOS) SuSE Mageia Other

advantage - makes bouncer page feel less 'bouncy'. disadvantage - no good place to give selection advice,unless you put it all on the bouncer, which is cluttered and muddy.

1. Keep it all on one page, but make a configurator. At top of page would be three buttons, (windows) (mac) (linux)

all initially gray. Clicking on one gives another line of buttons - say you choose windows, you get Choosing between 32 and 64 bit windows blah blah (32 bit) (64 bit) This time there's a sensible default (32 bit) so we select that one. There's a visual device, such as a big arrow pointing down, to make it clear you're in a wizard like dialog with the machine.

advantage: user feels guided through process. Offers user chance to consider choices. (Think for example the number of windows 64 downloads we get who probably should be using win32). disadvantages: introduces new UI technique, a bit, usually a bad thing.

1. Use a real wizard series of pages asking questions about os, width, etc with forward/back arrows and a 'timeline'

advantages: gives the advantages of twisty passages without the twisty passage feel disadvantage: few more clicks for the 'just give me what I want' crowd.

A side note - I'm going to put the new stuff on a new URI and 'orphan' the old stuff, so those with auto build scripts don't have to rev them.

So, not done with design pain.

Jan, this over to you for comments, if you comment in next few hours I'll implement today.

[JanWielemaker]

I see the dilemmas.

There is one thing I do not like: that are submenus. They are hard to navigate as the choice to make is often unclear. Touch devices make the interaction often no fun either.

There are indeed two pages that must remain: /download/stable and /download/devel because they are used by packaging systems that track for available new versions. These often download the HTML file and search for links that match a given regular expression. Of course, these pages do not to be easily reachable.

So, right now we have roughy this

• Download
  • Stable
  • By OS
  • Devel
  • By OS
  • Daily
  • Windows only
  • Old stuff
  • Source

No matter what you do, it seems a messy choice process:

- Stable/Devel
  Students should use stable, but many researchers need devel.
- 32/64 bits
  Unlike what you state, 64-bits is typically the right choice
  if you can as virtually no machine has less than 4Gb.  The
  64-bit version poses no limits (and is cooler :-).
- Binary/Source
  Depends on the OS.  On Windows, binaries are easier.  MacOS
  gets less obvious as Mac is troubled by binary compatibility
  issues, notably around X11.  On Linux, source is easiest,
  unless you have Ubuntu, then you can use the PPA.  Typically
  you should suggests students to use the package for their
  linux version if available (but most likely they never visit
  the download page if there is a package).
- Finally, you want to be able to download the matching
  documentation.

My not-so-good HCI gut feelings think about a series of vertical radio buttons places left-to-right with the various options. Like this (details to be decided).

Series  OS       Archicture  Source/Binary

Stable  Windows  32-bit  Source
Devel   MacOS    64-bit  Binary
        Linux

Intially, you can select anything. If you make a selection, all incompatible ones are greyed out. If there is enough info, there are two download buttons, one for the source/binary and one for the documentation, as well as a description.

We could preselect based on the browser id. This would require a `reset' button to clear all menus if you download for another plaform as you are browsing.

I guess the download page will need a bit of JavaScript to activate the menus. The server would dynamically create a JavaScript array with all available version (all that logic is in download.pl).

If you select source and stable/binary, the download becomes available, but further selection could use the description field to reflect comments. I propose to fetch all descriptions from wiki pages, so it is easy to edit them. These can just follow a simple general naming schema.

[Anniepoo]

There are indeed two pages that must remain: /download/stable and /download/devel because they are used by packaging systems that track for available new versions.

I'm definitely leaving everything that's currently up 'up'. All new stuff will be on new handlers.

As for submenus, while I heartily dislike the fiddly nature of the menus we've got, I think that's an issue with the menu implementation. I think download windows/mac/linux is pretty clear, so not sure what you mean? do you mean there's a lack of feedback which you're selecting?
Agree, on mobile devices none of this is fun, but we're not a very mobile friendly site anyway.

Typical of why I want things to automatically go stale: "Unlike what you state, 64-bits is typically the right choice if you can as virtually no machine has less than 4Gb. The 64-bit version poses no limits (and is cooler :-)." I didn't know that, because somewhere in the docs is a 'should I use 32 or 64?' and you say 'most people should use 32'

I got as far as starting to implement this in static html:

  My not-so-good HCI gut feelings think about a series of vertical
  radio buttons places left-to-right with the various options. Like
  this (details to be decided).

What's CLEAR here is the task - get a working swi prolog on the machine. That at least is a rock we can cling to.

I decided it was going to be massively confusing when I got a look at it.

But you and I are both groping towards the 'wizard' pattern.

http://www.welie.com/patterns/showPattern.php?patternID=wizard

'wizard' avoids the confusion of the mass of radio buttons by only presenting one or a few choices at a time. The wizard contains a 'map' of where you are and the whole process (you're on step 3 of 9, here's all the steps) so you don't feel you're in the maze of twisty passages, and it's a common UI design for good knowledge reuse, especially for those who use windows much, as it's a common idiom on that platform.

I'll implement wizard. It also works to guide people through the build, and I'll put 'write hello world' at the end of it, which will vastly improve the first 10 minutes experience for students.

Only downside is that it doesn't feel like command line on-the-bare-metal power hacker. I'm willing to live with that. You might take a minor bit of flak from the jeering section.

[Anniepoo]

Something I've been fairly blind to, but just 'got' - I rarely use git to checkout sources because I'm rarely installing on a server where I have no browser to do a download with.

[Anniepoo]

I installed pl-devel on a machine for OSU this morning. I kept track of my pain points:

1. the git instructions aren't on the git page, you have to scroll down to see they're an obscure link on the bottom.
2. I had the 'am I about to put 75 zillion files in my home directory' moment just before running the clone. Only then did I see the

Initial checkout is achieved using the command below, which creates a directory pl-devel below the current directory.

which is verbose and buries the lede.

we continue to bury the lede by

The download does not contain generated documentation and configuration files, neither the required stand-alone submodules.

which only attorneys and theologians will get means 'you're only getting half the system'.

Next, having apparently decided that nobody would actually want all the instructions in one place, we get

Next, consult the file INSTALL for further instructions for installing SWI-Prolog from source.

Further, this isn't one paragraph, it's two (fixed some of these issues)

Now I try to follow this. I have no trouble getting the sources and run ./prepare it stops and asks me if I want to d/l dovcumentation. Being a bit leery of programmers whose idea of fun is 'saving time' by doing complicated partial installs, I usually install everything, so I install the docs. Oops! I need curl, and it's not on the machine. and the error message doesn't tell me if it's safe to rerun ./prepare So I install curl and rerun ./prepare it can't find autoconf and tells me to install it. It wisely tells me to install autoconf and re-run this script which is reassuring, I know I don't have to reinstall and start over, but gives no directions to install autoconf

this not being my first rodeo, I install with sudo apt-get install autoconf

and prepare works and I again have the awkward 'now read rest of instructions in install'

the INSTALL file is long, and I'm on a terminal to a remote machine, so I get punished.

I start reading scary advice about the long and painful road of non gcc compilers and it sounds like this system's unstable and hard to use.

The important information is unhandily buried in the middle of the file

"In the normal case the following should do:"

No, actually, that only builds half of it...

But the next section 'Building the swi-prolog packages' looks like material I don't need, so I'd be ignoring it and/or prolog altogether if this were my first time installing swipl instead of my 14th or so.

I run the ./configure script, which puts out enough verbiage that it's a good thing there's a handy reminder on the end to build the packages. Of course first it says I have to run make (though I read something about gmake, so I'm baffled, but in do what I'm told land), and then make install, so annie's likely to forget that in her little pea brain.

This not actually being Annie's first rodeo, she's smart enough to not follow the instructions to do make install, and does

sudo make install

By now any mention of packages has scrolled off the screen and wouldn't be in Annie's pea brain, but this is not by now annie's first clown show, and she remembers to build packages... but has no directions.

that's ok, she's done this enough to know how, but doubts this is true of J Random language geek who'se installing languages and has become less impressed with what a professional, sleek system swipl is.

so annie tries to cd packages - oops, where's packages? finally cd ../packages

./configure

which informs me that I'm missing -lXpm and gives advice about installing X, and the more useful advice that I should install the dependencies first - OOOOPppps, nice to know that now, at the end of the install. OK, the dependencies are described in the README.linux file - but there's no README.linux file, so I fossick about for it and find it in the parent

which gives me COMPLETELY DIFFERENT BUILD DIRECTIONS . .. oh, that's slick!

What it DOESN"T give me is a SET OF DEPENDENCIES !!!

so I remember seeing them on the swipl site (people active in the site redesign find this accessible. CS 303 "programming languages" students find it less so)

and nope nope, the page http://swi-prolog.org/build/unix.html STILL doesn't give me the dependencies

fortunately I rmemeber something about LinuxDistro.txt, and that and the tiny text link at bottom of page get me to

http://swi-prolog.org/build/LinuxDistro.txt

which gets me to

http://swi-prolog.org/build/Debian.html

which, whoopie! has the dependencies

It also has a bunch of verbiage and a handy invitation to build the documentation, a pain filled process guaranteed to chase off half our audience.

I get rewarded by not having libunwind8-dev available

sudo apt-get install \ build-essential autoconf curl chrpath \ ncurses-dev libreadline-dev libunwind8-dev \ libgmp-dev \ libxext-dev libice-dev libjpeg-dev libxinerama-dev libxft-dev \ libxpm-dev libxt-dev pkg-config \ libssl-dev \ unixodbc-dev \ openjdk-7-jdk junit \ zlib1g-dev libarchive-dev \ libossp-uuid-dev

There's an admonition (buried under 'older Debian distros', but I'm on a machine set up by OSU IT department about 4 months ago) that they ship with libunwind7-dev

I distinctly remember the first time I encountered this error, not getting that that applied to me and spending half an hour or so struggling with this

I've now spent a while struggling installing deps, and don't exactly remmeber where in the install process I've gotten to, or what I'm doing. fortunately I'm writing this document and can scroll back. Doubt that's available to most people doing this.

wonder if I can rerun configure, figure I'll try, and it seems to happily run. I see a warning, which worries me, but it scrolls off.

Now, there's nothing to warn me I have to run make and make install. I've just done this a few times.

that completes and I run

sudo make install

Since this isn't annie's first rodeo and I know not to install half the system for myself only.

At this point I have a running install, but no advice or guidance how to check that I do.

[JanWielemaker]

Thanks for the story. It surely hints at many places where the docs should be clarified, linked, be consistent, etc :-) Don't expect it to become easy though. There are just too many dependencies and too many platforms with there own tweaks. That is why there are things like Macports, Homebrew and similar systems and why packaged software on Linux is so popular.

Updated INSTALL, README.git and prepare to deal with quite a few of the comments above. Please check.

[Anniepoo]

in INSTALL I'd suggest moving the section " Building SWI-Prolog lite" and "Building the SWI-Prolog Packages" to the top. People don't actually read most documents top to bottom - particularly things like install directions.

• % ./configure --prefix=PREFIX
• % ./configure --prefix=PREFIX

would be better with a real example, so people know exactly what to put in PREFIX

[Anniepoo]

I have a suggestion how we might proceed with the design (as opposed to implementation).

What if we make a little expert system 'swi-prolog install advisor'. This could be something as simple as building atop the AMZI 'birds' tutorial. I'm imagining something that runs at the top level and doesn't take significant resources to develop.

This would let us document all the install decision points without worrying about user interface issues. Once we had the expert system we could figure out how to 'package' it for the website.

I'm certainly not dead set on doing this, but it feels like we're swimming in a sea of interacting issues. Getting some clarity on what the UI's to do separate from the UI itself might help.

[Anniepoo]

ok, saw your attachment.

your set of radio buttons and mine were pretty much the same. I have pretty good evidence that it's going to be confusing to users to see the other radio buttons change. This is precisely why the wizard pattern does what it does - present it's questions on separate pages. No one questions why you only get to see one question at a time. It's to prevent people from being confused by the commotion 'backstage'.

The whole process is meant to resemble that of consulting a human expert. Example (person buying part to fix car):

clerk: how can I help you? customer: My battery light is on, I need a new battery clerk: Well, the battery light could be on because the alternator's not charging. customer: oh, sure - I drove it a ways and then the headlights got dim and it stopped. clerk: yes, that's the alternator. What make car do you have? customer: it's a Mazda 626 clerk: with the 3.2 liter engine? customer: I don't know clerk: well, what year is it?
customer: it's a 2006 clerk: oh, then yes, it's 3.2 liter, let me see if we've got one <goes in back, returns with part> customer: Yes, I think that's like the one on my car clerk: ok, be sure to bring in the old one and your receipt, you get $10 back for the old core.

The customer has a problem, and even believes they have a solution. The clerk asks one question at a time, and changes her vision of what the customer needs as she gathers information. For example, the customer asks for a battery, but the clerk knows that often it's not the battery that's the problem, but the alternator. She gives the customer relevant information, and the customer changes his mind. He might have said 'no, I did XYZ and it's the battery'. The customer's ultimately in charge (and I'm sure people who work in auto parts stores knowingly have to sell the wrong part to customers all the time). But here they cooperate to get what the customer really wants - a running car. Once they agree it's the alternator, the clerk needs additional information to find out what model alternator the customer wants. She's flexible how she does that - the customer doesn't know the engine size, but does know the year, which is enough to determine the engine size. But, though the process is complex, the customer's never confused because the clerk offers the options one at a time.

[JanWielemaker]

On 02/02/2014 10:07 PM, Anne Ogborn wrote:

ok, saw your attachment.

your set of radio buttons and mine were pretty much the same. I have pretty good evidence that it's going to be confusing to users to see the other radio buttons change. This is precisely why the wizard pattern does what it does - present it's questions on separate pages. No one questions why you only get to see one question at a time. It's to prevent people from being confused by the commotion 'backstage'.

Hmmm. I'm still not convinced, because:

• There is no clear flow for your wizard. You basically have to deal with 4 questions, but there is no obvious starting point. For some the OS is leading, for others the sources, for some stable/devel, etc. So, there are going to be 6 clicks to download: (1) download page, (2-5) the 4 wizard clicks and (6) the download button.
• Because there is no obvious starting point, you are likely to face the user with question s/he cannot answer. Only as s/he goes through the process, s/he'll understand the options and quite likely needs to restart.

This problem is simply different from the average product selection because there are so many options and there are so different users. So, if you want Skype, yes you want the binary that runs on your OS, period. The average student user also wants this, and we can give that by pre-selecting the menu. The users we are most interested in though have a wide range of different requirements and do need some support as I see them quite often taking the wrong one. I believe these people are smart enough to deal with some radio buttons, giving some meaningful popups (?) to explain the dimensions.

Cheers --- Jan