First, let me define what I mean by “effective.” An effective spec must be inviting and easy to understand so the whole development team can participate in the design. This way they can catch any problems, and their support can be won early. If a spec is so technical that only engineers can understand it, the marketing department will not feel part of the audience and will not look at it carefully. If a spec is not detailed enough or if the details shown are irrelevant—like unrealistic placeholder data—the spec will be taken as a suggestion and not the blueprint for the user interface. A spec must be detailed, but not too detailed.
An effective, usable spec therefore serves two main purposes: First, it elicits feedback early, which helps to avoid problems and misunderstandings later on. It’s especially important that clients are able to identify any missing functionality in the design, for example. Second, an effective spec ensures the software stays in line with the designer’s intentions as it?s built—in other words, the spec is precise enough that a competent engineer will build the interface as it was designed.
What’s wrong with the traditional spec
For many people in the industry, a large paper document with lots of tables and cross-references is what immediately comes to mind based on the success criteria I just identified. For some managers, it is hard to imagine anything else, so you may encounter resistance toward new approaches. But there are some problems with traditional specs:
First of all, maintaining such a spec can be nearly as complex as maintaining the software it’s supposed to specify. The traditional spec is often too technical and the level of detail too great to keep it in sync with changes. Because of this, in my experience, complicated traditional specs are abandoned quickly. When that happens, the spec is no longer authoritative, but a collection of out-of-date suggestions that are easy to ignore.
The level of detail in a spec should be significantly less than the level of detail in the implementation. A common reason to insist on a detailed document is to make sure that every error condition is covered. I submit that the user interface designer’s job is to cover the common cases well. This includes common errors, but not all possible errors. Obscure error cases should be handled without involving the user, anyway. A spec built around error cases makes it hard to see the forest for the trees. Programming languages are much better suited to this level of detail than English.
If you need to seek approval for the design, a long, highly technical document can scare busy executives and marketing people into procrastination. They have difficulty finding large blocks of uninterrupted time to review it, and it’s usually a chore you have to nag them into performing.
By abandoning the traditional idea of a spec in favor of a usable spec, you can deliver something that’s fun to show off, easy to understand, and confidence-inspiring.
To create a usable spec, ask yourself the same questions you do when creating usable software: Who is the audience? What are they capable of understanding? What will get them involved? Once you know the answers to these questions, you can create a spec that truly meets everyone’s needs. Don’t be afraid to think outside the box. Here are a few examples of nontraditional specs:
Demonstrate real interactions
Why can’t a spec include an audio recording? When putting together specs for telephone-based speech recognition systems, for instance, I have found this to be one of the best ways to get feedback. An audio recording can realistically portray a typical interaction with such a system. Ideally it uses professional voice talent and the same production standards as the final product. But as long as the caller and the voice of the system can be distinguished, this is not strictly necessary. A written script—like the script for a play, not the type in programming languages—also works well. Be careful though: most voice application designs are reviewed on paper, where the tone is more formal, which leads to telephone systems that sound stilted instead of conversational. But either way can be much easier to understand than a complex technical document.
Make every detail count
For a graphical interface, prototypes are useful, but not often considered a specification. In order to function well as a spec, a prototype must be detailed and use example data that has been carefully chosen to reveal key details about how the system works. You will have to explain that the prototype is meant to specify the system’s behavior and appearance exactly, to the pixel, and spell out the few cases where the prototype does not cover things completely. But much of what would be verbiage in a traditional spec is implicit in a prototype. In a sense, a prototype can help you achieve selective disclosure: people who want a high-level overview can glance at it, and those who need to understand the details can ponder the ones you’ve provided.
Speak the developer’s language
To get your design built the way you intended, the closer the prototype matches the developer’s construction tools, the better. HTML leads to code much more readily than Photoshop, for example. In any case, the level of detail captured in a prototype or pixel-accurate screenshot is much easier to understand than if you wrote the 1,000 words every one of your pictures is worth.
Make the invisible visible
Sometimes, when the behind-the-scenes behaviors of a system are especially complicated or especially interesting to the audience for the spec, it’s useful to make them visible. Draw the database table in a debug window and show the information being inserted. Good developers tend to do this, though often by just spewing text messages to a window somewhere. It usually takes only a little extra effort to make the normally invisible modules visible, and if it takes a lot of effort, you are probably discovering bugs in the process!
Mapping it out
In addition to providing the most accurate screenshots, recordings, and other artifacts you can produce, it’s also important to provide a map of the system. I have noticed that the best developers do this, too. What is a map? A map shows the interrelationships of the important screens, states, or programs, and also serves as a to-do list for the user interface programmer. It is usually one or two pages—small enough that it can be viewed in its entirety in the free space next to your keyboard. It is a printed document, needing the full resolution and permanence of paper.
The map can be screenshots with arrows linking them, a quick reference guide listing commands, or a state transition table. It can be primarily visual, or mainly text, depending on the project and the developers. Again, a single artifact can provide an overview or important details, depending on what the developer needs at the time.
Other benefits of usable specs
Usable specs can also be helpful in usability testing, marketing, and to crystallize leadership. You can even get the manual finished at the same time as the product.
A well-crafted usable spec can be easy enough even for potential users to understand, so they can be valuable tools in usability testing. For example, full-blown prototypes can be put to use almost immediately to get feedback on the most common tasks. An audio recording can be broken apart and played to potential users to get reactions. Showing screenshots in sequence can be a good way to get users to talk through problems.
Marketing and sales always want the product before it is ready. Since a usable spec is meant to match the system’s outward appearance and behavior exactly, it can be used in presentations and collateral. This has the added benefit of locking in the design, by reigning in the tendency to request changes while it?s being implemented.
Software projects often lack a tangible way of gauging progress. The user interface is the most tangible part of a software project and the most closely tied to the customer. Members of the development team can use the spec to understand how what they are building will serve the needs of real people, as well as how close they are to being finished.
Once a usable spec is complete, user documentation can be written. The technical writer is the first non-engineer who has to understand the complete system in all its detail. He or she can use the spec to find conceptual problems early—something that’s hard to explain is probably not easy to use or build.
Cost and effort
The cost of producing a usable spec depends a lot on how comfortable you are with the tools developers use. A pixel-accurate Photoshop document will serve a web developer well, but HTML can serve as scaffolding to get them up to speed even faster. An audio file representing a phone call is useful, but you can clarify many of the system’s operations implicitly using a sequence of files whose names have been carefully chosen to coordinate with the sections of the map you provided.
My own background is in programming, but I don’t provide production-quality code as a design artifact. I’ve provided audio files, HTML, Visual Basic prototypes, and even plain old graphics with some written notes. I have found that the more technically capable my client is, the less technical my deliverables need to be.
You might be wondering if you can combine a usable spec with a traditional one. I don?t recommend it. Maintenance is one issue. Authority is the other. It is difficult to manage updating multiple artifacts during the iterative part of the design phase. And you want just one artifact to serve as the source for settling questions about how things are supposed to work.
Finally, as clear as your deliverables may be, you will still need to explain precisely how you mean for them to be received. Recognize that a nontraditional spec will be new for everybody involved, and that you will have to answer questions about the process and explain some things a few different ways—everybody absorbs information differently. This takes diplomacy, and I find it easier to be diplomatic while showing someone a picture than citing chapter 3, section 2, subsection 4, paragraph 5, the second table.
Usability applies to our deliverables as much as to our designs. Creating a usable spec is an excellent way for us as designers to make things easier for the rest of the team. In my experience, this effort is appreciated and rewarded with cooperation and greater appreciation for the importance of our work.