The Effective Designer

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.

Tips

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.

Scope

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.

Context

References

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.

Personas

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.

Primary

You MUST declare a primary persona.

Secondary

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

Storyboards

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.

Foundation

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?

Language

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?

Framework

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

Orientation

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.

Wayfinding

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

Idiom

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?

Modes

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

Zones

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

Modules

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.

Controls

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.

Finish

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

Presentation

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.

Categories

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

Visual Design

Standards

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

Style

Identify any planned stylistic deviations from the standards cited above.

Colors

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

Typography

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

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.

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.