Experiencing Code for Oakland


Saturday last I attended Code For Oakland because I was curious about hackathons and the #gov20 movement.  This was to be my first exposure to both.

I took BART from 24th and Mission in San Francisco to 19th and Broadway in Oakland and then walked down to the Kaiser Auditorium on Lakeshore Drive.  As I emerged to the street and took in the striking  serpentine-green I. Magnin building I noted that feeling I always get when I go to Oakland, namely, that what I don’t know about Oakland could sink a battleship.  It was 8:15 am on a Saturday morning, rainy, gray and very quiet.

The Kaiser Auditorium building impresses from the outside with its scale.  It has a grand modernist  persona distinctly distinct from the art deco environment I’d just walked through.  A small paper sign on the door invited me to walk around back for Code for Oakland.

On the inside the modernist theme continued with floating escalators that brought me up to the mezzanine level past a black and white photo homage to Henry J. Kaiser that felt like looking at a 60’s era LIFE magazine.  I was warmly greeted at the Code for Oakland registration desk, grabbed a muffin, some coffee and sat down to wait for I wasn’t sure what.

The lobby was buzzing with the hum of 100 people or so when, at 9am, we were asked to sit down in the auditorium.  Susan Mernit gave a nice welcome and clear overview of the day, then we embarked on what I thought was a brave endeavor: a brief self introduction by everyone in the audience!

My concerns were completely misplaced; the experience was fascinating.  The diverse crowd skewed white/male/geek but far, far less than any tech event I have ever been to with lots of women and people of all colors. The professional breakdown seemed to be along a non-profit to tech continuum with a few student and government outliers.  As I listened to the different voices explaining their respective reasons for volunteering their Saturday, I wondered what factor was the biggest diversity driver: #gov20 or Oakland?

After introductions we were asked to self select into groups to work on the project ideas that had been collected in earlier community meetings, and during the self-introductions.  I was pleased to find some interest in the idea I had suggested to create a simple SMS messaging system for community organizers.  After some milling about the groups moved into the lobby and settled down around the tables set up there.


Our team consisted of myself, Ryan Jarvinen (@ryanjarvinen), Lamont Nelson (@thelamontnelson), Alan Palazzolo (@zzolo), and Keith Tivon Gregory (@tivon).  Except for the extreme gender bias, we were a reasonable mirror of the diversity in the larger group; as the lone Gen X-er (and just barely squeaking into that cohort!) I significantly raised the average age of our otherwise solidly Gen Y crew.  Our overlapping skill sets easily covered experience design, front and back end coding we would need for our project.

As we began brainstorming about the product, which we named ‘ComTxt’ (COMmunity TeXTing), two key ideas emerged.  First, a crucial success factor for community organization is the ability to provide the community with notifications (of upcoming meetings, actions, notable successes, etc.).  Second, the one technology constant among groups of diverse racial and/or socio-economic status (as might be found in an urban neighborhood or as the parents in a public school) is text messaging.  Certainly email is common, but it is by no means ubiquitous, and while phone trees can work, they are inefficient and manually intensive.  Essentially everyone, however, has an SMS-capable mobile phone these days.  Therefore, a system that enabled an organizer to broadcast text messages to a community of subscribers would be a useful tool for advancing community process.

We transformed these observations into a simple vision: a mailing-list for text messages. With this “good-enough” consensus on the basic product vision, we created some sketchy personas (PTA president, teacher, neighborhood activist) and very simple use cases for each.  The PTA president use case was representative: instead of having to collect email addresses at each PTA meeting (and then manually transcribe them), with ComTxt she would be able to display a simple poster that told anyone wishing to receive updates from the PTA to text the name of the school to a particular number.

After a brief break to consume the satisfying and complimentary lunch of sandwiches, chips and cookies, we began to identify the technologies and frameworks we’d use to build our proof of concept.  At this point we had about 4 hours left before the team presentations would begin at 4:30pm.  I was silently dubious that we could go from zero code to a working prototype in that amount of time.  My partners were relatively unconcerned because they understood something I had not yet internalized: we weren’t starting with zero code.

In fact our starting point was the remarkable world of frameworks, APIs and services that is the current web development environment. The programming reality of today is that there is so much pre-existing functionality, documentation and examples available via a web browser that no online project ever starts from zero. My team’s ensuing discussion of exactly which API or service to use was largely over my head, and though I am certain real nuances were being discussed, I think the guys would admit the discussion wasn’t much different than debating which is the best tacqueria in San Francisco.  In the end I believe we ended up creating a node.js solution that connects with the Twilio platform, but I may have missed an abbreviation or two.

By this point in the process we had made a seamless and almost unspoken transition from group process to each of us executing as individuals on the tasks to which we were respectively best suited.  Ryan gathered and returned to us information about the pros and cons of various text messaging platforms he’d learned from other groups, and he set up the Github repository we’d be using.  Alan and Lamont dived into the details of our chosen APIs and began writing the code to implement the simple set of commands ComTxt would understand.  Meanwhile, Keith and I collaborated on a prototype web UI for accessing the service, complete with some initial ideas about branding including a logo.


And suddenly it was 4:15 and our prototype didn’t work!  Undeterred, we quickly agreed on how to replace our planned demo with a PowerPoint show which I was still finishing even as I moved from our work table into the auditorium to watch the other teams present.

Watching the other presentations I began to feel like I was seeing the beginning of something real and transformative, even if I still couldn’t exactly articulate what it was. Gov 2.0 may not yet be truly changing lives, but I am certain it will and soon.  Last Saturday I saw one good, and useful, idea after another presented and in most cases actually working with a degree of polish and functionality that was remarkable given the few hours the teams had had to create them.  I got an emotional thrill from the energy and enthusiasm for positive change that had coalesced into these fascinating projects.

Literally moments before our turn to present, Alan, grin on his face, leaned over and told me the system was working!  It turns out as I had been watching the other presentations spellbound, he, Lamont and Ryan had continued coding and had solved the blocking issue.  I rapidly added a telephone number to our title slide and we all went up to present.  The audience understand our simple idea right away and shared our smiles when, after texting a subscription request to ComTxt, our phones buzzed in unison with a message from Alan:

Code for Oakland is great!

Sent from ComTxt

Getting Started with Accessibility

The Challenge

The paradox of web accessibility is that learning how to achieve it is not very accessible!

The problem is figuring out where to start. While there are a number of obviously relevant standards and examples available online, it was hard for me, as an accessibility novice, to sort through these guidelines to help our development team construct a set of concrete tasks that would return the greatest accessibility improvement for the least effort.

As it turned out, the thing I needed in order to understand how to prioritize our efforts, was to spend a day and a half sharing our upcoming release of JasperServer with a customer and that customer’s accessibility consultant. The results of this experience were both humbling and encouraging. The humbling part was the discovery that in its current state our brand new interface framework was not very accessible. The encouraging part was that with just a few hours work, once I knew what to do, I was able to use the systematic nature of our new system to make significant accessibility improvements.

The key to all this, of course, was the opportunity to work with experts in a real-world setting, and to be able to make changes and test them in real-time. While there will be no substitute for this experience, I’ve distilled my learnings into the following list, which I hope could be helpful to any web designer trying to understand how to begin improving the accessibility of his application.

Comply with Keyboard Standards

Users of screen reader software do not ever use a mouse for two reasons. First, they drive the screen reader software through keyboard commands so leaving the keyboard is awkward. Second, the rapid movement of the mouse tends to overwhelm the screen reader software which cannot keep up with the rapid change in input focus. While JAWS (a popular commercial screen reader) does have a ‘virtual’ mouse that permits a user to simulate a mouse click via the keyboard when nothing else will work, this cannot be relied upon because it is not part of any general standard. As a result, in order to be accessible, all required user events must have keyboard equivalents. In addition, these keyboard equivalents should meet the standard expectation (e.g. return key follows a hyperlink) to make them most useful and intuitive.

The key point here is that by using the screen reader experience as the baseline design context, we will also achieve accessibility for the larger community of users who are sighted but must, or prefer to, use a keyboard and not a mouse.

Embrace ARIA

The ARIA standard (Accessible Rich Internet Applications) is being widely adopted by the accessibility community. We tested ARIA markup with two screen readers, JAWS and NVDA (an open source screen reader) and found that both were well along in supporting the ARIA standard by providing appropriate context-specific instructions when encountering ARIA markup.

In general, adding ARIA markup is very low risk as it takes the form of element attributes that have no direct effect on rendering or behavior. Some of the attributes—particularly those targeted at improving orientation (ARIA ‘landmarks’)—improve accessibility instantly. Other attributes, such as those associated with what ARIA terms as ‘widgets’ can’t be added until supporting interactive scripting is also added because these attributes cause the screen reader to announce behaviors that must be supported with custom scripting.

Add Headings

Adding heading tags to the markup was a simple and effective method for improving a screen reader user’s ability to navigate pages. We also learned that it was not a problem for the headings and the ARIA landmarks to provide essentially redundant information. Screen reader users have the ability to navigate by heading or by landmark, often switch between the approaches depending upon what appears to be working best and don’t have a problem sorting out any redundancy.

Provide Non-Visual Feedback

It is common now in web applications for a user event to trigger an update to only part of a page. While this change is generally obvious to a sighted user, it is completely hidden from a blind user. There are ARIA standards for dealing with this exact issue by triggering alerts that will be spoken by screen readers. These attributes must be added to any scripting that dynamically updates pages, or generates error messages and alerts.

Fix Links

Web applications can be written to assign HREFs to anchor tags dynamically. Unfortunately, anchor tags without HREF attributes are not recognized by screen readers. This limitation can be addressed by adding empty or dummy HREF attributes to anchor tags but the implementation must be tested in all target browsers as there is inconsistency in how browsers treat the placeholder HREF attributes.

Develop Internal Best Practices for Accessibility

One cannot create an accessible application overnight. It will happen over time as long as an organization has a development culture in which accessibility is given priority. This can be helped along with simple tactical steps such as ‘Accessibility Checklist’ for developers and more strategic ones such as requiring that QA personnel, designers and developers build up a comfort level with using screen readers for testing prototypes and production code. In order for this to happen along with other priorities the best approach will be to establish that accessibility is neither an afterthought nor a special case, but part of creating semantically sound markup that benefits all users.

Work with an Accessibility Consultant

To achieve more than perfunctory accessibility compliance it is crucial to develop an ongoing relationship with an Accessibility consultant. There are several reasons for this. First, building a culture where accessibility is a core value requires that development personnel meet and observe individuals who rely on assistive technologies. Second, while QA tests can be created to validate standards compliance, observing real disabled users is the only way to know if an application has achieved real world accessibility. Third, as standards and assistive technologies are still in a significant state of flux, any organization, but particularly one where the understanding of how to implement accessibility is immature, will benefit from advice and guidance from an expert source.


The reality of accessibility is that it is no different from usability or simplicity or any other system characteristic: it can only be achieved by making it an ongoing and central priority.

While this might sound as if accessibility will then compete with other priorities, in fact improving accessibility helps to advance the quality of the user experiences for all client applications. In essence, accessibility is about delivering markup to assistive technologies that is appropriate for those technologies. Seen in this light, there is little difference between designing for accessibility and designing for mobile or any other experience. In all cases what needs to happen is that the application server delivers to each interface client code appropriate to its particular capabilities. As there is no doubt that support for a diversity of devices is the future for all software applications, all that needs to be done to improve accessibility compliance is to always consider assistive technologies in the mix of supported devices.

A Picture of Simplification

My friend and Jaspersoft colleague Matt Dahlman recently forwarded me a nice image he’d made that captures the essence of JIF, our new interface framework.  In Matt’s words:

The attached image shows the actual HTML code behind the menus that a user sees in v3.7 vs v4.0. It makes the idea pretty clear that a developer will find this new system cleaner, easier to customize, and generally better.

Thanks Matt, this is a great way to visualize the simplification JIF has brought to JasperReports Server.

Truth is, we’ve actually made things 3 times simpler than even this picture shows!

Matt is actually showing only one of the 3 different menu systems in 3.7.  Yes, believe it or not, in the bad old pre-JIF days JasperServer had 3 totally different menu systems, each used in different parts of the application.  These menus did not share markup, logic or presentation code and learning to customize one didn’t teach you a thing about customizing either of the other two.

JIF has a single menu system for the entire application with a simple, standardized method for customizing content and appearance.

Just what you’d expect from a state of the art interface framework.

Why Renovating the UI Layer is Hard


About one year ago I was extremely excited that my colleagues and I at Jaspersoft were about to embark on a re-design of the UI for our flagship product, Jaspersoft Report Server.

Actually, it was more than a re-design, it was a complete renovation of the UI layer.  All of our existing markup, styles and script would be replaced with a standards-based framework of our own creation.

I had conceived and sold this project to Engineering, Marketing and our senior executives because I truly believed this renovation was the required and foundational enabler for a host of initiatives.  Primary would be the development of a great user experience, but I also expected it would enable greater community involvement in our development process, more efficient development cycles, faster prototyping, and better stakeholder communication.

I still believe all that.

But man oh man, at what a cost!

The official project estimate was 6 months. My belief was that it would actually take 8. In reality, all said and done, it will take us 12!

We began the project with a team of 4.  We will end the project with a team of 12.

Words of wisdom from my former manager at Apple, Bob Baxley, ring in my ears daily. When I arrived at Apple (for my brief tenure there) the store website had just undergone a major re-design. Discussing that experience with me, Bob said “those of us who were here for the re-design feel more like it was something we survived rather than something we accomplished.”

With our UI renovation nearly behind me, I now fully appreciate the feeling that Bob was trying to explain.  I also have a pretty clear idea of why this project was so much harder than we expected:

  • We did not, and frankly could not, accurately understand the true amount of re-work that was going to be required
  • In trying to create a state of the art result, we sometimes had to innovate, but had not accounted for the time of the resulting iteration cycles
  • We could not always keep ourselves, or our internal partners, to the limited project scope we had set
  • We overestimated the efficiency that standardization would bring to the design specification process.


We knew from the outset that we were going to replace every single line of markup and css during this project.  We also knew we were going to replace the lion’s share of the javascript. We even anticipated that we would be creating a new kind of an ‘API’ between the javascript and the css selectors to be able to use class names to trigger certain UI behaviors (e.g. anything with class ‘button’ will automatically get mouse event handlers applied).

We actually did a decent job estimating this work, and we even structured the project schedule to include two entire phases devoted to designing the CSS/Javascript API and then testing it by building two workflows before applying the new framework to the entire product.

However, the piece we did not truly consider in our planning was the cost of re-writing all the logic embedded in the markup itself.  We are a Java shop, so we use JSP files to create the markup delivered to the browser.  In this project we did not correctly estimate the time cost to re-think, replace, and modify the logic in these files.  I think our mistake was to base our estimate on an extrapolation of our experience converting over a few pages.  The problems with this procedure were, first, that in our test pages we did not actually change all the little things we needed to change in the production version so we ended up with an overly optimistic effort/page factor.  Second, the ‘average’ page was a myth.  Every page took at least as much time to re-write as our ‘average’ estimate and many took far, far longer.

Cutting Edge or Bleeding Edge?

Our goal in this project was to create a modern UI framework, comparable in concept, if not scope, with YUI or Dijit/Dojo or MochaUI.  Why we rolled our own is another post, but the point here is that these things are still quite new and it isn’t always clear what is the best way to solve the various issues involved in creating them.  While we could rely on standards documentation to help us conceptually, transferring those conceptual ideas to an actual implementation involved innovation and risk.

For example, we had ambitious goals with respect to improving the accessibility of our interface during the re-design.  However, as we progressed we learned that without experience doing this work, ambiguity in the accessibility standards documentation meant that we spent a considerable amount of time debating the best implementation approach, testing ideas, re-doing work and even ultimately giving up on some goals as we ran out of schedule time.

Scope Creep

The agreed scope of this project was to renovate completely the interface framework, while leaving the fundamental application navigation and workflows intact.  In practice it turned out that we could not keep to this restriction for 3 reasons.  The first was simply that sometimes it was not possible.  Our new framework includes forward looking design concepts and interactions and in some cases we could not map our older, circa 2002 UI directly onto the new framework.

The second reason was sometimes it was just too painful to leave the old design in place.  For example in situations where it was clear that we could replace a 3 step wizard (complete with 3 page loads) with a single, reasonably simple form, we went ahead and did just that.  Each time we made this kind of usability improvement we cost ourselves the time involved in re-writing page logic.

Finally, our internal partners had trouble keeping to the original scope agreement.  During this project nearly the entire marketing team at the company turned over and the new team chose to re-open some of the design decisions we made with the previous team.  Discussing and implementing these changes cost us several man-weeks of effort.

Not Cookie Cutter

A major driver for this project was to improve the consistency of our interface.  The old UI had been built up over several years by different developers working without any design management so different sections of our product had different design conventions, interactions and even look and feel.

Our assumption was that cleaning up this inconsistency would be straightforward once we had designed and built a systematic layout structure and a standardized set of components.  In practice we found that the application of these standards to our existing pages and workflows was more time consuming than we expected.  As we began to convert pages we found that we were missing both layouts and components.  We also learned that even our augmented set of standards still only applied about 80% of the time–nearly every page had some particular feature that required some custom layout work or specialized markup.

There were also a few unfortunate cases in the oldest part of the application where what was expected to be a simple task turned into days and days of unplanned code re-factoring.  This occurred where our state of the art approach to  separating the logic, structure and presentation layers of the UI required us to untangle monolithic server code.  For example, in the section of our application that displays paginated reports, the trivial sounding task of making the pagination controls into a general component, instead of a custom element embedded in each report, took literally 10 times the expected effort.


Anyone who has ever been part of renovating a house has experienced the budget-busting moment when opening up a wall reveals an entirely unexpected set of existing conditions.  These painful moments serve as humbling (and expensive) reminders that it is simply not possible to anticipate all the risks involved in a truly complex project.

We discovered that a home renovation was an excellent analogy for our experience replacing the UI layer for JasperReports Server.  The project took far longer than we expected, and was much much more painful that we anticipated.  The outcome, however, like a lovely new kitchen, will be a pleasure to work with for years to come.

Adding Search to Jasperserver: A Cautionary Tale


Our upcoming 3.7 release of Jasperserver includes a major new feature: faceted search.

As the first major initiative I pushed for after joining Jaspersoft as User Experience Architect, search was my pet project. While I am certain the new functionality has improved the user experience for some users, I believe, due to flaws in the design process I led, we missed an opportunity to deliver an interface that made finding objects in our system dramatically simpler for all users.

This post is an illustrated attempt to break down that design process in the hopes that others may benefit from understanding the errors I made and the lessons that I have learned (or, sadly, re-learned).

Lessons (Re)learned

To help you parse this long post, I’ll begin by listing the lessons I took away from the search project:

  • Never assume the primary persona or the essential use cases
  • Mockups are not prototypes
  • Evolution is an easy sell; revolution requires data
  • Performance matters

And most importantly:


The Starting Point: An Expert Interface

In Jasperserver 3.5 the only way users can find reports and other objects contained in the system is via an interface that looks like this:

This design is obviously modeled on a file browser.  As such, it suffers from the problem shared by all browse experiences, namely that it is a tool for experts, not novices.

Because it is designed to expose the file structure, a browse tool provides a good experience for the administrator who needs to create or maintain that structure.  However, for the business user who knows the name of a report stored in the repository, but no idea of the logic the administrator used to construct the structure, using a browse interface is a bit like an easter egg hunt. I explain this issue in more detail in this post.

As the percentage of Jasperserver users who maintain repositories is considerably smaller than the percentage of Jasperserver users who want to find the reports contained within the repositories, my feeling was that the repository interface was optimized for the wrong persona.  I believed that we could fix this usability issue by adding a search functionality to our server, and then optimizing the repository interface around the new search feature.

I made this argument in a number of product planning sessions and succeeded in getting a search project prioritized for our next development cycle.  Paradoxically, this early success was the source of my biggest mistake.  By focussing on functionality, I sold the idea of adding search, but, as it turned out, never actually got buy-in for the crucial underlying assumption that we should optimize our design for the repository user, rather than the repository creator.

The Mockups

In my initial storyboards for the new repository experience, I proposed a faceted search navigation combined with a federated results display:

The point of the default design was to present the objects in the system in terms of meta data most relevant to a business user.  However, because we did need to support the administrative workflow for creating and maintaining the hierarchical structure, I proposed that users be able to opt-in to a view of the file structure, by pressing a button:

If exposed, in addition to various management functions, the folders could be used to control the scope of the search, and, combined with the search string and the other facets used to refine the found set. I thought this design was starting a bit complicated, but as viewing the folders was an opt-in experience, I was comfortable that by default we would be offering a simpler presentation of the repository objects.

I used images like these in storyboards detailing a variety of use cases that I shared with project stakeholders. The storyboards were met with a favorable response and we moved into production.

In retrospect I now understand that this was the point where I made a second, crucial mistake.  This was that I moved directly to storyboards without first establishing with the stakeholders what the critical use cases actually were.  If I had begun by asking the stakeholders to help me define the most important use cases I think we would have uncovered almost immediately the fact that many of the stakeholders did not share my main assumption that we should optimize the design for business users.  Instead, I presented storyboards that embodied the business user persona assumption implicitly.  As a result stakeholder approval of these storyboards really only meant that the storyboards told stories that made sense.  Approval did not mean, as I assumed, that the storyboards made sense and told the stories we all thought were most important!

First Prototype and First Hiccup

This problem only began to be clear to me when we finally presented our first working prototype.  It didn’t have the all the filters working and it didn’t group the results by type, but was otherwise quite faithful to the mockups:

And, as proposed, folders could be exposed and used to set the search scope:

The reaction of several project stakeholders to this prototype first alerted me to the fact that we did not all share my fundamental assumption that we were optimizing this design for repository users, rather than administrators.

The trouble began when the stakeholders finally understood that the folders were acting to set search scope, not to define the location of the panel that displayed objects.  You can see this in the screenshot above.  The folder ‘Ad Hoc Components’ is selected, but if you look carefully at the path shown for the displayed objects, you will see that these objects are all actually located in a child folder ‘Topics.’  From a search perspective this is correct: the search is finding all objects that match the current search string (in this case the empty string “”) located within the selected folder and all its children.

However, from a browse perspective this is an incorrect result because only results located in the currently selected folder should be visible.  In this case, this would mean no results would display. Once this difference was understood, the stakeholders insisted that the administrative user could no longer use the interface effectively because it would not meet his browse expectations.

Compromise Mode

It was now clear to me that I had made strategic blunders in managing the design process for this project.  Rather than leading the good fight to improve the experience for our agreed upon primary persona, I understood that I was perceived by several critical stakeholders as forcing a dramatic change in interaction model to which they had not agreed and strongly objected.

Suddenly finding myself without consensus regarding the primary design persona, and lacking data demonstrating that the change I proposed would be acceptable to the existing administrative users, I decided that the most responsible thing for me to do was find a compromise design that would quell the stakeholder rebellion and move the project forward.

The first step towards this compromise was the addition of a means by which a savvy user could switch the experience from search to browse mode. While I accepted the political need for this adding this mode,  I knew it probably meant my vision of using search to simplify the repository experience was out the window.

That said, I continued to hope we could still offer a simpler default display.  Here, in the next working prototype, the initial view continued to look like the storyboards, including the results grouping:

However, when folders were exposed, a mode switch was also revealed:

If the user switched to browse mode, then the results display only showed objects located within the current folder (in this case no objects):

The search field and filters would continue to work in this mode, but would be of limited utility as they could only be used to refine the display of the objects within the current folder.

This prototype was a failure for two reasons.  The first was that in playing with it, it became clear that the hidden mode switch was totally confusing. The second issue was that several stakeholders continued to object strongly to the idea that one had to opt-in to see the folders because to quote one “folders are first class filters.”

After presenting this prototype I realized my belief in compromise was overly optimistic.  In fact, what was required on my part, given the political situation, was complete capitulation.  I needed to accept that in order to close this project I had to re-set my fundamental assumption and accept that most stakeholder believed the primary persona for this project was the administrative user, not the business user I had been designing for.

Evolution not Revolution

With this insight, it was clear to me what I needed to do to get to a design all the stakeholders would accept: treat search as an incremental evolution of the existing experience rather than a revolutionary change.

The next prototype looked like this:

The functionality was the same as the previous prototype but the presentation was now designed to promote folders as the primary organizational structure.  The interaction mode was still by default search, but the mode switch was made more prominent and visible at all times.

With this presentational change, stakeholder resistance evaporated.

Performance: the unkindest cut of all

Having accepted the shift in priority, I had made my peace with the new presentation when a final problem surfaced: performance.  It turned out that for technical reasons having to do with how the repository database stored object meta data, creating the object type groupings was extremely inefficient.  The user experience impact of this was that a search that attempted to bring back all types of objects and group them by type would take a very long time when the repository got large.

This discovery came very late in the the production process when no appetite remained for any further design changes.  As a result we settled on the expedient solution of breaking the simple faceting model for object type.  While the rest of the filters defaulted to some kind of ‘all’ setting, the one for type would default to a custom group named ‘Visualizations’ that contained the object types most interesting to business users: reports, dashboards, and analyses.  You can see this change if you compare the screenshot above which shows a filter set to ‘All types’ versus the one below that shows the same filter set to ‘Visualizations.’

With this change we knowingly made it harder to understand the conceptual model underlying the filters.  The only other short-term alternative would have been to abandon the grouping concept entirely, but, lacking any kind of ‘popularity’ algorithm (an earlier sacrifice to project schedule, deemed acceptable because of the grouping concept) this would have meant that by default searches would return arcane object types (e.g. JDBC connections) with the same priority as frequently used types (e.g. Reports).


The conclusion I draw from this post mortem is that the last lesson I listed above is really the most important: no pet projects.

The bottom line here is that, because I was personally invested in this project, I skipped or at least shortcut, a number of steps that I know are part of a successful design project.  Probably the most critical error I made was to confuse the process of selling the project to stakeholders with the user and stakeholder research I should have done, but didn’t, before beginning the design phase.   I compounded this error by relying on mockups, rather than prototypes, to communicate status until far too late in the development phase.  Finally, I did not engage deeply enough with the technical aspects of the project to avoid being surprised by last minute performance issues.

Shifting to the bright side, the early feedback I’ve gotten from users familiar with our product is that faceted search does, in fact, materially improve the experience of finding and interacting with system objects.   In other words, what we did achieve with this project was a tangible improvement in user experience compared to our previous product release.  While my initial design aspirations were larger than that, this positive outcome raises the perennial question of design leadership: when is the incremental, but safe, value offered by evolution a more responsible strategy than the dramatic, but risky, value offered by revolution?

Experience Requirements Document

One of the most significant organizational challenges I encounter as a professional software designer is that, almost universally, the business environments in which I work do not have an established first class design document.

By this I mean there is no existing expectation in the product development process for a document that is intended to capture the design intent of the project.  There will nearly always be an expectation for a document capturing the business justification and market needs for the product–this is usually called the MRD or Marketing Requirements Document.  Commonly  there will be one or more engineering responses to MRD called things like the PRD (Project Requirements Document) or the TS (Technical Specification). And then there is some kind of quality assurance document, often called the QA Test Plan.

But, aside from Apple, I have never found at any software company for which I have worked either full-time or as consultant, a formal, first class design document as part of the established development process.  In this respect, software development is sadly unique.  Pick any other engineering endeavor and you will always find, built-in to the development process, an expectation for some kind of formal design documentation that has the role of conveying the visual and experiential aspects of the proposed project.

In my effort to enlighten the backwards software development world, I have championed the need to include design documentation in the standard project documentation. Generally the first question asked when I introduce this idea is ‘what would this document look like?’ Here, below, please find my latest version of the answer to this question.

Experience Requirements Document

About this Template
This template contains 5 sections. They are structured to present information ordered from highest level to lowest level of abstraction.
The document begins with a discussion of project scope, then moves to a context section that is intended to clarify the fundamental environment and constraints in which this proposed design must succeed.
After describing context, the final three sections are organized around the concept of a house.
The foundation section should define the basic concepts upon which your planned experience depends, in the same way that a house is utterly dependent upon its foundation in order to stand.
The framework section should describe the kinds of affordances, layout and navigation your experience will provide in order to meet user needs. This section is analogous to the framing, plumbing, wiring, fenestration, etc that provides structure, access and functionality to a house.
The finish section describes the presentation and labeling that combine to provide what the user perceives as look and feel. The analogy here is to the paint, trim, moulding, cabinet hardware and other details that are the things people actually touch and see in a house.
This document structure is loosely adapted from the work ‘The Elements of User Experience ‘ by Jesse James Garret.

  1. Don’t re-invent the wheel. If you can ‘complete’ any section of this document by referencing a previous project, or an existing element in the product’s UI framework, definitely do so!
  2. You don’t have to fill out every section. Some may not be relevant to you. Leave the heading, but note that no information is required.
  3. In general, focus on describing the new things your project is adding to the product user experience. Particularly with respect to the Finish section, you may find you are not adding anything that is not already part of the existing UI framework. If this is case, simply state this and be done. If however you are extending the framework, be very clear about how.


Design Issue

Explain the fundamental design issue that needs to be addressed with this project. You may be able to draw from the MRD here in terms of the business case or user scenarios.

Proposed Solution

Describe the design proposal in a nutshell. You’ve got the entire rest of the document to provide details so here just create the ‘elevator pitch.’ Just one or two sentences capturing the major UE impact and benefits.



Links to relevant documents. Definitely include other internal planning docs like MRD & PRD but also any design references, examples of the experience you plan to create, etc.


If personas are defined in MRD then echo them here. Add whatever special circumstances or details are needed to improve the reader’s understanding of how these personas are relevant to the project, or how they constrain the UE design.


You MUST declare a primary persona.


Optional but do include if considerations of other personas influence this experience.


Add links here to attached storyboards. If possible, indicate what use cases/scenarios the storyboards cover. If you can connect the storyboards to scenarios or use cases appearing in the MRD or PRD so much the better.

Of course you may include pieces of the storyboards or any other illustrations as clarifying images in any of the sections below.


The foundation section should define the basic concepts upon which your planned experience depends, in the same way that a house is utterly dependent upon its foundation in order to stand.

Conceptual Design

Conceptual Model

What is the process or ‘machine’ the user must create in his mind’s eye in order to understand the basic logic of this experience? If you explain this by citing an existing standard model that’s good. If you need to define a new model, explain why.

Information Architecture

What are the basic pieces of this experience and how are they related hierarchically? How does data flow through this experience?


What unique terminology is used by this experience? What is the domain of human endeavor from which this terminology is drawn?

Interaction Design

Interaction Model

What can the user do? How can he do it? If he pushes on this lever, what door will open? Again, cite an existing model if possible, and if not possible, explain why you need a new one.

Error Model

What kinds of mistakes can the user make and what are the planned mitigations for these errors?


The framework section should describe the kinds of affordances, layout and navigation your experience will provide in order to meet user needs. This section is analogous to the framing, plumbing, wiring, fenestration, etc that provides structure, access and functionality to a house.

Navigation Design


What context does the user imagine himself to be in during this experience? How does he keep track of this context? Are there places where he may lose his context? Identify any modes in this experience and explain why they are required.


How does the user move through this experience? How does he arrive here, how does he leave and how does he get back?

Interface Design


What basic type of experience is this? Is it a designer, is it a viewer, or is it more like a blog entry? Can you give examples of experiences that this one will be similar to?


How does the user switch modes, how does he know what mode he is in?


Describe the basic display areas involved in this experience. Don’t forget to include overlays, inlays, pop ups, floating panels, etc.


Provide detail as required to explain the modules found in the zones you’ve described above. Do explicitly call out any modules that are new addition to the product’s UI framework.


Provide detail as required to explain the special controls found in any of the modules. In general you will only need to detail controls this experience will add to the product’s existing UI framework.


The finish section describes the presentation and labeling that combine to provide what the user perceives as look and feel. The analogy here is to the paint, trim, moulding, cabinet hardware and other details that are the things people actually touch and see in a house.

Information Design


Describe how the information architecture is communicated and displayed to the user. Also highlight any presentation components or designs that are novel to this experience as compared to the existing product experience.


Identify the categories that are used to organize the information presented in this experience.

Visual Design


List with references all the standards you are following in this design.


Identify any planned stylistic deviations from the standards cited above.


Define your color palette or any additions to the palette identified in the standards section.


Give examples of any typographic conventions or styles in this experience not already covered in the standards section.

Breaking Down Search and Browse

The point of this post is to describe concisely the technical difference between search and browse.

In so doing I will expose a paradox:

browse experiences are more intuitive but less novice-oriented

search experiences are less intuitive but more novice-oriented.

Examining the Difference

From a computational perspective searching and browsing have a single specific difference:

browse: display objects in terms of a fixed hierarchical structure

search: display objects in terms of shared intrinsic properties.

Let’s examine how this difference plays out in some example interfaces.

Example 1: The Mac Finder

mac finder browsing

The Mac Finder is a great example because, while it prioritizes browsing, it also attempts to integrate the two navigational modalities.

The characteristics of this experience are that:

  • the default interaction mode is browse
  • the organizing principle of the display is directory structure; objects are displayed only in terms of their location within that structure.
    • objects to the left are always closer to the hierarchical root than objects to the right.
    • each pane displays the contents of the selected directory to its right.
  • the design assumption of this display is that the file structure has meaning to the user, and displaying it will help him find his way to the object he seeks.

The overall utility of this display for navigation turns on this last assumption: if the file structure taxonomy has meaning to the user then an interface that faithfully traverses it will be useful to him.

Of course, we all know that this assumption is often not true.  The structure may not meaningful to the user because:

  • he didn’t build it
  • he did build it, but then he forgot the rules he used to build it
  • it is incomprehensibly vast and idiosyncratic like the world wide web.

These issues are in fact different aspects of a single problem: while the concept of using hierarchical categories to organize objects is natural and intuitive, the assumptions underlying any particular taxonomy are arbitrary and idiosyncratic. Thus a browse interface is only efficient as an object-finding tool for a user already expert in the taxonomy being displayed in the tool. Any other user must spend time exploring the hierarchy before he can use it to locate objects of interest to him.

For this reason search is often a more efficient navigational experience because it permits the user to create object displays organized around a particular object characteristic that is meaningful to him.

The Mac Finder affords a transition to search by integrating into the experience in two ways:

  1. the search box in the upper right
  2. the saved search options in the last grouping in the right hand pane.

While these search affordances are visually integrated into the UI, using either of them produces a modal shift in the display:

Mac Finder Searching

The most apparent difference between display modes is that the panes have disappeared.  With them has gone the concept of directionality or left to right flow because that presentation relied upon the assumption that the most important object property to display was the container in which the object was located.  Instead this display groups objects in terms of a user-defined search query, in this case ‘search mode’.

And yet, in this example, reference to structure is still provided as a refinement feature.  At the top of the display pane there is a set of controls that can be used to set the search scope (where to look for objects) and the search field (what to look at within each object):

scope bar

These buttons represent a type of affordance called a filter.  Interacting with them provides the user with a means to reduce (or expand) the objects matched by his search in terms of additional dimensions beyond the query string.

Put another way, these buttons expose to the observant user that the true search expression is more complicated than simply the text query he entered.  In fact the complete expression involves, by default, certain types of metadata.  The fact that the Mac Finder offers structurally-based refinement options by default is an honest reflection that search has been added on top of a system that has as its intrinsic organizing principle the concept of directory structure.

The next obvious question is what about a system that does not have a simple, pre-defined organizational principle? What is the interface that permits users to locate objects in this system?  Let’s consider the world’s most successful example of this kind of interface: Google.

Example 2: Google Search Results

Google Spelling disambiguator

The Google search results page is excellent counter-example to the Mac Finder because it comes at the problem of directing users to objects of interest from the absolutely opposite perspective.

The characteristics of this experience are that:

  • the default interaction mode is search
  • the organizing principle of the display is the user’s query; objects are displayed in terms of their relevance to this query
    • objects at the top are always more relevant (per the rules of Google’s search algorithm) than objects below
    • each listing highlights (literally) the way it is relevant to the user’s query.
  • the design assumption of this display is that the search term has meaning to the user, and organizing objects around it will help him find the best match for his query.

The overall utility of this display for navigation turns on this last assumption: if the query describes the user’s true interest then an interface that displays objects relevant to that query will be useful to him.

Of course, we all know that this assumption is often not true.  The search may not return results meaningful to the user because:

  • the query is spelled incorrectly
  • the query is ambiguous
  • the search algorithm defines relevance in a way that is not intuitive for the user

These issues are in fact different aspects of a single problem: creating a precise rational expression that represents our current interest is hard for people to do. Recognizing this issue, the Google experience provides a number of subtle cues and affordances that help an inherently irrational human create a concise and rational search expression.  In fact, in the image above we can see how Google automatically offers a spelling correction to address one significant source of error.

In the image below we see another tool that Google provides to help users create more specific queries called facets.

Screen shot 2009-11-21 at 10.44.50 AM

Selecting any of the choices in the left pane narrows the results in the right pane accordingly. If multiple selections are made they are applied sequentially to produce a more and more refined set of results. It turns out that this refinement experience feels very browse-like even though it does not actually result in traversing a single fixed taxonomy. This suggests a clarification to the statement that the process of browsing is intuitive. In fact what is intuitive is the process of refinement: iteratively evaluating and editing information until I have thrown away enough of what I don’t want that I can see clearly that which I do want.


Thus we conclude our brief tour of these two interfaces with the interesting observation that, in an effort to overcome the limitations of browse the Mac Finder offers search and, in an effort to make search disambiguation more intuitive Google offers facets as a browse-like option.

Here, then, are our design takeaways:

  1. The more navigating your system feels like a process of refinement the more intuitive it will feel
    1. Navigation tells a story; told correctly the end coincides with the place the user wants to be
    2. His reward for each navigational decision he makes should be an obvious elimination of information from his view
  2. Because browsing is for experts there are only two cases where a browse interface is good design:
    1. You are certain your users will be experts in the system taxonomy
    2. You are certain you want your users to become experts in the system taxonomy
  3. Except for the two exceptions the best choice for navigational design is to base it upon search
    1. Search is better for novices because it does not require an expert understanding of the system taxonomy
    2. Most people are novices with respect to most system taxonomies
  4. A search-based navigational system can, but does not have to, include an actual search field
    1. Links can be used as affordances that trigger searches
    2. Facets can be used to offer an intuitive refinement experience

Simple Storyboard Production Technique

This is a simple technique for transforming a set of images into a sequenced multi-page PDF storyboard.

Limitation is that it is Mac-only because it relies on Preview, the can opener utility that ships with the Mac OS.

  1. Create your storyboard images; you are on your own here
  2. Open 1 of the images with Preview, it doesn’t matter which one
  3. Open the ‘sidebar’ in Preview that let’s you visualize thumbnails of the ‘pages’ in the document; you’ll see a representation of your image there
  4. In the Finder, select ALL the rest of your storyboard images
  5. Drag them into the Preview sidebar
  6. If necessary, drag the images into the correct sequence
  7. Select ALL the images in the sidebar (tip: select the first, scroll to bottom, shift-click last)
  8. File > Print Selected Images…
    1. this option is usually ‘Print…’
    2. the fact that it changes when Preview is displaying, and you select, multiple images is part of the secret sauce
  9. In the resulting Print dialog, make whatever formatting changes you need (i.e. ‘orientation’)
  10. Instead of pressing Print button, use menu in lower left to ‘Save as PDF…’
  11. You are done; you now have a multi-page PDF of your images.

The added bonus is that not only can you share this file like any PDF, you can also easily present it using the ‘slideshow’ feature of Preview.

New Leaf at Jaspersoft

This week is my one year anniversary at Jaspersoft as User Experience Architect.

Appropriately, but coincidentally, this week we are beginning a new approach to integrating UX into the development process.

The New Leaf

This change in methodology is our response to a failed project: a visual redesign of Jasperserver, our flagship product. In this case ‘failure’ was a schedule issue: late in the cycle we realized that we would not meet our release target unless we pulled the redesign from the plan, and reverted it out of trunk.

There are probably 5 or 6 particular reasons why this project failed.  I think it would be useful to take these point by point in some future post. Today, however, I am more interested in how our experience is part of a more general issue: how do organizations combine user-centered design with the agile development methodology?

Faced with our recent failure in solving this integration we are making two fundamental changes:

  1. We are recognizing that not all projects are created equal. Many can be done in parallel but some must be sequenced before other development.
  2. Previously we managed all projects as in terms of requirements, design and production.  Going forward we are recognizing that we need to manage certain projects (see point 1) in terms requirements, design, user experience architecture, software architecture and production.

Recognizing the Special Projects

With respect to the first point, my initial guess as to what defines a project that must be done sequentially is one that creates a change in the object model of any software layer. A sexier and more compact formulation would be to say that architecture projects must be sequenced.

You might recognize such a project because it involves changing or upgrading a named framework.  Switching from a homemade set of Javascript utilities to jQuery is a good example. Upgrading to a newer version of Spring would be another.

Our ‘Visual Redesign’ project is another good example. At one level the architecture that was changing was purely visual: the visual logic of the pages, the color palette, the typography and the massing and organization of the white space. However, the true focus of the project was to change the markup structure in order to enable the new, beautiful and flexible visual design. This is the crucial point.  Once we agreed to change the markup, we were agreeing to change the DOM structure, and this meant invalidating many of the assumptions upon which the event handling scripting was based. This in turn made it impossible to move forward with almost any other work.

It’s the interface, stupid

The simple reason parallel development was blocked was that converting over to the new framework broke the UI.  We learned very quickly that a broken UI made it challenging to progress even on initiatives that were classified as infrastructure projects. The reason, obvious in retrospect, is that in the execution of essentially all projects the graphical user interface is the primary tool developers use to evaluate whether their changes are successfully meeting requirements. In addition, without a functioning UI, all QA testing, both manual and automated, ground to a halt.

As an initial mitigation we tried to maintain both the old and new UI environments simultaneously. Within two weeks of embarking on this program we realized that rather than reduce risk, the parallel approach dramatically increased it by literally doubling our development effort. Given that the business could not double our available schedule, maintaining two environments meant guaranteeing we would miss our target release date.

This all came to a head after a week in which the entire team worked long hours and yet we saw almost no meaningful progress on new features and zero reduction in our bug count.  At this point, even I, the primary cheerleader for the project, had to admit it was time to back out.

Three Heads Are More Rational Than Two

Following this painful but entirely rational decision (OK, maybe there was a little bit of yelling) we’ve begun looking at how we are going to get the Visual Redesign into our next release. As mentioned above, in addition to realizing a visual redesign is a special kind of project we have increased the body count at the planning table.  Whereas in round one we staffed the planning phase with just myself, the UX architect, and  a software architect, this time around we are including a third player: the technical manager.

Our thought is that this addition will produce two distinct benefits.  First, it means the cycles the software architect has available for this project will be devoted to the production of his most valuable contribution: a rock-solid interactive architecture.  This time he will not have to split his effort and allegiance between producing the best architecture and planning the steps involved in implementing it within the allotted schedule.

Second, including the technical manager from the beginning means that as soon as the frameworks begin to form, be they conceptual models or interactive frameworks, they will be critiqued by a third party who has no personal investment in the vision they represent, but is simply concerned with their tactical production implications. Our hope is that this practical critique will help trim the fat from the architectural visions without producing the compromise in ideals that occurs when talented individuals spar endlessly over the myriad important, but ultimately arbitrary, decisions that comprise a holistic and internally consistent vision.

That’s the theory, anyway.