You love to hate them - UI specs!

User interface specifications can be a tricky undertaking. Over the years, I have written them to many degrees of detail and have, more often than not, been disappointed with the end result. There is a very delicate balance between *enough* information and *too much* information. The appropriate amount of detail is very dependant on the audience. I still haven't found that perfect balance, but here are some lessons I have learned along the way.

The Audiences

Offshore teams often need more

Let's just be realistic. We're talking about both language and cultural differences here, so it's important to be concise. I have worked primarily with offshore teams in India, but also in Russia and other countries. Ambiguous documentation can lead to scores of questions (and thus development delays) and/or an end product that does not meet the design intent or business expectations. As I understand it, many offshore development teams tend to fluctuate in both size and members to meet project deadlines, so there are a lot more people to communicate to with the documentation. It should be presumed that the development work will be split up such that at least some percentage of the resources do not attain accumulated project knowledge.

Americans hate to read

I'm American and resemble this remark when it comes to dry documentation like UI specs, so I can get away with saying this. Heck, I hate to write them even though I appreciate it as a necessary evil in many (not all) cases. So, here we have exactly the opposite problem that we may experience with offshore teams. The lengthier and more thorough (and textual) the document, the less likely it is to be read and followed. Does this mean that the text is unnecessary? Not remotely. Without the specifications to force consistency, it is likely that if you have 12 different programmers coding your screens you will get 12 different results. Some prime areas for inconsistency without a spec are: overall screen layout, form field orders, methods of handling form validation, wording of error messages, placement order of buttons, behavioral aspects such as hover and click states, etc. These may seem like minor things, but they can collectively have a large impact on usability and the perceived quality of the end product.

Playing telephone

I have worked with some teams with onsite leads and offshore development teams. This actually seems to work better than having an entirely offshore team since the local lead can help with communication, but can become a game of "telephone" where the message gets increasingly less accurate as it moves down the line. So, the need for documentation is no less under this structure, but it can take some of the onus off of the user experience lead in educating the development team.

Client stakeholders love/hate it

This is beginning to sound like a rant... and maybe it is a bit... but here is yet another audience inconsistency. I have had clients that love, love, loved the level of documentation that I provided and others that thought it a complete waste of time and literally asked me to somehow turn a 80-page spec document into a 2-page summary. With screenshots. You may gape now.

Leaving a legacy

Yet another audience to consider is the one that doesn't exist yet - the future design and development teams that will perform maintenance and add features to the product. These teams must understand the original design intent to ensure the consistency of the user interface as it evolves over time. I have never actually had the opportunity to speak to this audience to find out how they felt about my documentation, but I would guess that they either love it or completely ignore it.

Some Tips

1. Play nice with others

Decide who will document what

It's helpful to reduce repetition of the UI requirements as much as possible as this can lead to further inconsistencies and time burned in deciding (or arguing over) which document is correct. If you have a full project team which includes Business Analysts, User Experience Architects, and Technical Leads, it's important to decide which requirements are going where before anyone starts writing. My personal preference is something like this:

Functional Requirements and/or Use Cases

Maintained by the Business Analyst and should contain all of the business and high-level functional requirements. These should *not* contain user interface or technical requirements. Side rant: I could - and maybe will - write a whole article about how to write requirements and use cases without specifying UI.

User Interface Specifications

The responsibility of the User Experience Architect and should contain all user interface specific requirements such as design patterns, field lengths, form field orders, button locations, interactions and behaviors, state change transitions, etc. If it pertains to user interface behavior, usability, or visual design, it should be here.

Technical Specifications

These should be written and maintained by the Technical Lead and should contain specifics on technical implementation of both the business and UI requirements. Unfortunately, in my experience, documentation of technical requirements often falls off of the project radar. I think that it is very important for establishing coding consistencies on a development team - including technology platform, project structure, naming conventions, data management and error handling - just to name a few.

Decide what level of documentation is needed

You may still have some variation of the documents listed above at different degrees of detail. Depending on what else is happening with the project, you may not need quite as much detail. For example, if the User Experience Architect is working directly with the development team and delivering the front-end code, the UI Spec may not need to contain every aspect of the desired interaction. The field sizes, orders, and even some of the behaviors may be provided in the front end code so may not need to be documented. But don't forget about the QA team - they may be a consumer of the user interface specifications as well. I recommend following this rule: if it needs to be tested, it needs to be documented.

Present the UI to the development and QA teams often

These are really mini training sessions where you walk the development and QA teams through sections of the UI to ensure that everyone has the same initial understanding of how things should look and behave. This doesn't make documentation unnecessary, but should help to ensure at least a baseline understanding so that if the documentation is not consulted as often as it should be, the results will still be better. It also gives those team members an opportunity to ask questions and thus help you to make sure you haven't left anything important out. The earlier the Tech and QA leads are involved, the better. The Tech lead may be able to recommend user interface behaviors that are easier to implement which would still provide a good experience.

2. Simple and thorough at the same time

Be as visual as possible

A picture is worth a 1,000 page spec document.

Split things up

Come up with a logical divide for your specifications so that everything isn't in one huge document. I have found that splitting the documentation up into logical feature sets work best. This also seems to be how development teams commonly split up the work, so it works well for that audience.

Use bullets rather than paragraphs

Be as succinct as possible with specifications - bullets are great. This allows the reader to scan the details very quickly.

Use design patterns as much as possible

This is a good idea from a usability perspective as well as in documentation. The more consistency the user interface has, the more usable it will be. I have had the motto for a long time that even a bad user interface design can be usable if its at least consistent so that it can be learned. If you use design patterns, you can limit the amount of necessary screen-level specifications.

Find ways to limit updates

This one can be difficult in a fast moving project. I recommend reviewing the documentation thoroughly (maybe even a third-party review) before you deliver. This way, you will hopefully catch at least most of the holes before you pass it on. When you do have to make updates, make sure that they're communicated in detail and find ways to highlight them in the document so that the downstream team members can easily find them.

Keep cross-referencing down

Even if you have the same form field appearing in multiple screens, it may at times be necessary to copy the specification throughout the documentation. This sucks for you and there is more risk of creating discrepancies, but but it may be better for your audience. If they are constantly having to shuffle between documents to find all of the specifications they need, they're less likely to stick to them. And who can blame them? What a pain!

3. Do it yourself

The most successful projects I have worked on with the most consistent and highest quality results have been those where myself and my team has actually created the front end code. This is perhaps a bit controversial in the UX world and I agree that not everyone in the UX role will have the skills necessary to do it. I am a bit of an anomaly in that I started as a programmer. However, this can still be accomplished by including one or more front end developers in the UX process and developing the code as you design.

One advantage to this approach is that the UX designer as a front-end developer tends to be more passionate about design consistency. I have also found that it allows me to work out issues that would require some amount of rework if it got to a development team first and had to come back to the design team due to technical constraints. Having a front end developer working with the UX team and doing proof-of-concepts along the way could also mitigate this risk.

If your UXA doesn't have the front end coding skills and you just can't include a front end developer in the UX process, I think the best fallback strategy is to use a prototyping tool of your choice (could be as simple as wireframes) to draw out the intended behaviors in as much detail as possible. If you can make it even *seem* to work, you may be able to get across the intended behaviors without a lot of textual explanation - which is far too open to interpretation.