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 DocumentAbout 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.
- 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!
- 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.
- 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.
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.
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.
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.
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?
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.
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.
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?
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.
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.
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.