Roadmap for removing unnecessary JS and AJAX

This document is for recording thoughts and conclusions about where and how JS and AJAX should be minimized (removed) from the current design.

X#index

I don't think we reached a consensus here - either some work should be done to further deduplicate the infinite scrolling code, or these pages should become dumb forms which produce paginated search results.

project#show

This page is the main offender in terms of unnecessary JS and AJAX. Some amount of it is fairly minimal and visually pleasing (things like deleting datasets and buttons that disable saved on selection), but there are two major issues here:

1. File upload. Right now its a mess of form after form in modals. Maybe this should just become a series of form pages. This includes file upload and google upload - manual entry already has its own page, and while a bit JS heavy works well and shares code with dataset#edit.
2. Field editing. The system in place now is a total nightmare, if it got its own page for the purpose of editing, things might go a lot better in terms of code. We would need to make sure the template from file worked consistently with whatever changes were made to file upload as well.

visualization#show,displayVis

These obviously need JS to function, but the jquery tabs should be killed if possible, and the fate of dataset descriptions really needs to be discussed.

user#show

The 'my stuff' interface here needs a facelift. Badly.

In General

We have in-place editing options all over the place (first name, title, content, etc etc...). Should these stay mostly as is and only de-ajax the large unwieldy chunks? or should everything gain an edit page?

Motivations (according to Nat)

There are four reasons why I think the default answer for any client-side code in the project should be to remove it: maintenance burden, ease of automated testing, UI simplicity, and ease of tracking for UX analysis.

Maintenance Burden

Browser JavaScript logic tends to be complicated and fragile. The basic idea is that you write functions that are triggered by asynchronous events and then rewrite the page's HTML tree in place - this is already a difficult programming task before we even discuss what the code is specifically doing.

Rails provides conventional solutions to many of the problems that could be solved by JavaScript or AJAX, and provides all of its sane defaults and powerful tools (e.g. error logging) when those solutions are used.

The main justifications for JavaScript in spite of this goal are necessity and isolation. For example, there's basically no way to do an interactive visualization server side, and each visualization can be built as a stand-alone client side module that doesn't need to be understood in order to understand the operation of any of the rest of the site.

Since the iSense web site is maintained by part time college students, it's worth going as far as paying a visible cost in other areas to make the site easy to maintain.

Ease of Automated Testing

Rails provides an excellent built in framework for automatic testing that works well and quickly for server side logic. Most importantly, when used pervasively this allows regressions to be detected - old bugs should not come back when new bugs are fixed or new features are added.

Client side JavaScript code can be tested using this framework, but the only reliable way to do it involves launching a full copy of the Firefox web browser and simulating mouse and keyboard events. This slow, fiddly, doesn't cover browser-specific issues, and makes writing good tests relatively difficult.

The reason developers give for not testing a component is that testing is hard. At a certain point, any missing test is a bug and the only way to fix the missing test for an impossible to test component is to swap out the component for something that's testable.

UI Simplicity

The basic interaction model for the web (click a link to go to a new page, or fill in several fields and submit a form) have been the same for 20 years and are innately understood by every web user. It's possible to design better UIs than links and forms, but each time we depart from the standard we take a significant risk: Our novel UI may actually be worse than the default, and this can be true even if it looks like it's better.

The simplest example of this is failing to re-implement all of what the default UI provided - for example, a form can be completed entirely using the keyboard by tabbing between elements, selecting check boxes and radio buttons with the space bar and arrow keys, and submitting the form with the enter key. As soon as you do anything but a default form, all of that suddenly becomes your problem rather than the browser's problem.

The counter argument is always that the novel UI really is better, but that claim should require

UX Analysis

In order to improve the user experience for iSense, we really want to get some actual-user usage data. Getting people to use the site in a full on UX lab as they would use it in the wild seems difficult, so the next best thing is to track how users use the site. If every interaction hits the site as a simple page load, we can take a shot at doing this with simple log analysis. If a lot of the logic is client side and avoids server hits and page loads, we'll have to do this by instrumenting our JavaScript - if we do more than a trivial amount of that we basically lose at Maintenance Burden entirely.