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.
Getting creative
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.
*Engineers especially have trouble stopping with a problem statement, and proceed right into the solution. So we end up with “Customer needs Add Widget Button” instead of “customer needs a way to add widgets,”*
Tell me about it! I am joining this party a bit late (kind of 4 years late?) but, anyway…
I am working on my MSc thesis (with a Computer Science BSc) trying to compile a list of requirements based on a Goal-Directed process. I interviewed some people, made some personas from those (and some other data) and now I’m trying to get the requirements for the product (a mobile application)
It took me a long time, and it wasn’t until my supervisor finally told me, that I didn’t have to answer the question “how is the user going to add a widget? a button? telepathy? a link? how? how? how? HOW AM I SUPPOSED TO TO KNOW IT??!?”, but just mention that “there has to be a way to add a widget”, as you say.
Cheers!
I think the idea behind the article is really good. if the specs include both the technical part and the graphical part, if they are written in plain language rather than technical cliches, this is a good way to start a development process.
As for gui prototypes, I think they serve a good purpose, when client draws a lot of attention to detail, or when you don’t want to have any arguments post factum…. when it’s all written on paper, and signed off by both parties, it’s much easier. If the client does not like the way ui prototypes look, it makes sense to provide design mockups too. this way expectations can be managed in a smart way.
as for the “add widget button” vs “way to add widgets” problem, I think it all depends on what kind of client it is. I for one prefer the “add widget button” option for the specs (provided it’s been confirmed with client that he wants this solution specifically). at least this is the way we do it. Gleb, http://www.specshelp.com
Thanks for a great article Brian. I agree with most of your key points however my thoughts travel a different course.
I too am wondering how traditional specs can be improved with regard to specs and UI design. First off by ‘specs’ I assume you mean ‘Functional Specifications’, where I work we have 3 specs – Business, Functional/User, and Technical.
For our current project we have a Functional Spec which incorporates the user interface design, now well over 200 pages. It is impossible to maintain and noone wants to read it – its too big, takes too long to print etc. There is always a rush to finish the UI as the Functional Spec has to be ‘signed-off’ by stakeholders.
We have done a hifi wireframe in HTML, and everytime there’s a change to it, the spec must reflect the changes. The spec also has screenshots of all screens, and when we encounter problems with the wireframe at coding time, noone wants to make a big change as the specs has to change also. The people who create the wireframe are not the application coders, therefore the application coders ‘disown’ the html and expect it to be accessible, validate, and work in all browsers. One of the disadvantages of hifi html wireframes/prototypes I feel.
Anyhow, I digress. I would like to see a separation of functional spec and UI design. Stakeholders can sign off on the functional spec, develop the UI as a separate process. This means that the scope business rules, etc are complete and signed off. It also means that the stakeholders cannot hijack the design process – “I want a flashing logo or I’m not signing off”, or when you want to change something in the UI you dont need a stakeholder meeting.
Thanks for the comment.
I imagine that the wireframe is the de facto spec, the thing that everybody refers to day to day.
Your situation (which I obviously sympathize with) sounds like asking a building architect to represent all the information in a large blueprint in a series of 8 1/2 x 11 pages without using pictures. “Section 3.2.4: Bedroom. The bedroom provides facilities for sleeping, reading, and television watching if the optional television module is installed. The south wall includes two windows, which may be opened and closed by operating the latches (Part #3321, Anderson Windows) and moving the interior panes up and down…”
I’m not sure what you mean by the application coders “disowning” the prototype code. They expect it to be better quality?
Thanks for your reply Brian. The wireframe ‘becomes’ the spec because its easier to see webpages than read the spec.
The ‘developers’ in this case are the middle tier guys. They are too busy integrating the app with other enterprise systems and databases to care about the html. They assume the wireframe is a finished product, which it isnt. My experience with customers is that they too see a hifi wireframe and think its the finished product – but thats another article 🙂
I guess the question I am asking is “can we create more usable specs by separating functionality from design?” In my experience the functional specs require signoff from stakeholders, and the application is then developed and tested against these specs. The interface design should be a flexible and iterative process involving end users, designers, and implementing best practices – not tied up with stakeholders who want to dictate UI design.
The challenge of prototypes, especially hi-fi ones, is managing expectations. The same HTML can be seen as scaffolding that’s useful for someone who only expected screenshots, but it can also be not-good-enough code for someone who was expecting something else. Having recently implemented one of my HTML designs, I felt both ways!
It’s hard to get people to separate functionality in the abstract from the realization of it in the user interface. What you really need is a separation of problems from solutions. Logically, you need the solutions to flow from the problems, but technology products don’t always work that way.
Often, functional specs say things like, “User needs an Add Widget button” when in fact the user doesn’t need a button but just the capability to add widgets. Sometimes, clients don’t mind or notice that I don’t take premature UI design literally. Unfortunately, most people don’t have the design vocabulary to describe what they want without suggesting something concrete. Engineers especially (I am one so I can say this) have trouble stopping with a problem statement, and proceed right into the solution. So we end up with “Customer needs Add Widget Button” instead of “customer needs a way to add widgets,” or even better, “Customer’s current widget index card file makes it difficult to share widget information like part numbers with the Phoenix office.”
Once the concrete solution has been proposed, the UI designer has to explain why a change is needed, and so you end up arguing about the Add Widget button instead of what the best way to get widget part numbers to Phoenix. I find it helps if you can appear prescient by telling people they’re going to have this reaction well before any particular issue comes up, and that the UI might end up being quite different from just the sum of the functions suggested.
Joel Spolsky’s written a good (programmer-centric) set of articles on writing specs.
http://www.joelonsoftware.com/articles/fog0000000036.html
Worth a read if one of your main audiences is coders.
Thanks Brian for a wonderful article.
Yes, I agree with you on everything you said.
Well, up to certain point.
Your view of traditional spec might be different for certain organization. I worked in a large company, where it took many years to get all the groups in a company to agree on a process. So, to introduce nontraditional spec as part of the process will take very long time and buy in.
But if it’s a new company or even small startup, it might be easier. That’s just an assumption.
I don’t like very strict process, but some companies require development teams to follow very strict engineering process even if it’s not the best (sometimes to meet some standards).
In seperate note, I also wanted to comment on who should write the UI specs. Writing specs long time. You could hire somebody full time to write UI specs all day, but lot of companies won’t invest in something like that. So, we the UI desigers and engineers end up writing it. But lot of UI designers have very little training in writing good specs, especially for softwares. It’s hard to spend time writing “ideal” specs while doing user research and interaction design.
I really think writing effective spec should be done by technical products managers or program managers. I know in microsoft, this is how it’s done.
Yes, there are lot of bad things about microsoft, but their software engineering process is lot better than most companies out there.
So for some of us who do not have program managers with UI developmenet/design skills,
it just means more work for us.
By the way, if anybody knows of any good cheap software for producing and managing UI specs, let me know.
I agree with elements of your article, but the scope of the discussion is too small for me.
The problem with writing specs and why people find them hard to maintain is that they try to write them in word. Using a word processor is an impossibly difficult way to maintain something as complex as a spec.
There is also a widespread misconception (mainly web driven) that wireframes constitute a spec. IMHO they are not. Helpful, but not a spec.
To write a good spec You need to know functionally what you want to achieve in the product. You have to map these requirements to how you want to achieve them. This involves back end, front end, big end and all sorts of other ends but the main thing is to get to an end-to-end understanding of the product and why you are doing what you are doing.
People draw up wireframes too soon without thinking about the business processes and rules first. If you cannot clearly follow a line of thought from a wireframe justifiably back to a requirement then who said it should be there? Not the customer, that’s for sure.
Another thing that drives me nuts is that people don’t use the right tools. Forget Visio, forget HTML, forget word and forget Photoshop. These are all rubbish for doing a wireframe or lo-fi design.
Why? Because they do not capture information well. On a screen design you need to capture visual placement but also rules, definitions of screen areas, field names, button functions, interactions, etc… People do this by drawing something up in a drawing package then trying to assign information to it by writing a document to go with it. For example, to be any use to a developer, a design should indicate which fields from the database each field on the screen represents. Now watch your designers head explode when you give them a data model to decipher.
Even if you manage to finish one version of this complex task it will never get kept up to date as the wireframes change – it’s just too much effort.
The best tools to use for writing your spec and initial UI design are CASE tools such as System Architect, Enterprise Architect, RUP, etc…
Put your project requirements into such a tool and your spec will write itself when you press the export button. Draw your wireframes in a CASE tool and as you change the wireframes, UI elements, requirements, use cases etc so does your documentation. It really is that simple.
[Something worth noting is that your customer may not fully understand your spec and what the implications of it are. This means there should be some translation of your spec into a form they can understand. This is where a “usable spec” can help and I have drawn things up in many ways in the past to get people to understand. Whatever it takes…:]
Ji Kim said above:
“But lot of UI designers have very little training in writing good specs, especially for softwares.”
I agree with that entirely. The spec writing process can be hijacked by a range of people who are not skilled or trained in business process analysis, systems analysis, technical writing or systems design (architecture). The depth of knowledge is not there to understand anything except the superficial issues around wireframes.
Having said all this, I don’t believe in strict processes either. Use the analysis and design tools by figuring out what you want to get out of them – not by following a methodology just for the sake of it. Just make sure you justify your approach.
I also firmly believe in the 80 / 20 rule. It rules. Simply put, the 80/20 rule states that the relationship between input and output is rarely, if ever, balanced. When applied to work it means that approximately 20 percent of your efforts produce 80 percent of the results. Learning to recognize and then focus on that 20 percent is the key to making the most effective use of your time.
So, design 80% of your system/site/application then build something. The first iteration of design is often the most productive yet projects rarely achieve full iteration even once without prejudice. Yet you will spend 80% more time trying to figure out that elusive 20% extra detail. Iterate through a design and prototype just once and those elusive details will likely fall into your lap.
Going to a building analogy – used to be a surveyor in a previous life – an architect will design a building to an incredible level of detail that would make most software teams shudder. They can tell you how many nuts and bolts are required to build a 50 storey skyscraper and how many litres of paint for the stairwells.
Why? Because they are using the right tools and not re-inventing the wheel. CAD tools, technical drawing and standard processes mean they know exactly what to do to get the thing built. An architect also has an enormous level of technical understanding – he doesn’t just draw pictures. Again, this is how they can plan in such detail.
All of this rambling boils down to saying that a spec is requirements and functionality driven and a wireframe is an implementation task that is more than just pictures.
Cheers,
This is driving me crazy…I know I saw an example of a spec somewhere which went like
Screen
and then
All the elements in the screen in a table called ui elements or something like that.
If someone knows where it is please let me know the url. Thanks
Hello,
I am interested in tools which help me to create clean spec in short time.
Could you please send me some web sites?
Thank you in advance.
Cleo from Nantes, France.