Tuesday Mar 25, 2008

How do I write my UI specs?

First of all, I do not like to write.

Not just in English, but in any of the 3 languages I speak.

And for my fellow designers who do like to write (and are probably good at it), I have some bad news: no one likes to read specification documents. Even if the spec. is written in Tolstoy language, people prefer to enjoy Tolstoy language in a novel, in their spare time, and not at work, while developing or testing a complicated product full of hidden features and details.

So, I'd rather name my entry "How do I create my UI specs".

This is what a typical page of my spec looks like:

I use mostly Fireworks and Dreamweaver. I create my images (wireframes or mockups) in Fireworks, then place the image into a pre-made HTML table. The table consists of a nest for an image on the left, and an annotations column on the right.

UI Spec sections that I cover in my annotations column are the following:
1. Page Details: (project name, file name, release #, dates, version, designer name, and page type). Seems like a lot, but some of our products have very similar pages, and spec readers tend to print or bookmark one page here and there, and then have a difficult time recognizing the page they are looking at. By dedicating the top portion of annotations to housekeeping, I make this info always accessible, yet not in your face, so to speak.
2. User Scenario: here I indicate how the user gets to this particular page. Usually by performing an action on a previous spec page, or by opening an application, or both, so there could be several scenarios, and I believe it is necessary to mention all of them.
3. Interaction Rules: The most important part of the spec, of course. As you can see, the wireframe/mockup image is covered with numerous geometric shapes of different colors. These are snippets.

I drag a snippet from the Snippet Panel, give it a number (or a letter), and place it next to the component I'm about to describe in Interaction rules. Note, snippets live in HTML, and NOT in png world. I am not changing the image. Think of it as a sticker. If I have to change the button placing for example, I do not have to redraw the indicator in my png, just simply move the icon when I'm in Dreamweaver. Basically, my images and annotations live in different castles, which is quite handy for editing.
The fact that I place my annotations to the right of the image, makes it very easy to scan and find the appropriate number. If the spec reader is looking for the description of a particular component, he just has to find the right number in the Interaction Rules column and ignore the rest of the information.
4. Page Revision Details: I keep this section to indicate the changes that have been made during numerous revisions of my work. I also use this section to call out uncertainties and TBD areas that need my spec readers' attention. The icon for this section is a lettered blue triangle.
5. Notes: the least visible section - I keep the notes for myself here.

That's for the UI Spec sections.
Of course, there is an index page of all the pages in the spec, a brief description of the project, and special messages to the reader. I sometimes interlink the pages, especially if they are consequent steps of a particular use case.

If some of your spec readers can't access the spec online, you can always create a pdf using Acrobat. It is super easy: choose 'Create PDF doc' > 'From Web Page' > 'Entire Site'. If you are planning to create a PDF, don't forget to name your pages appropriately. Actually, even if you're not planning to create a PDF, still name your HTML pages appropriately - it's like good table manners.

Oh yeah, I use bright orange circle icon to indicate where the text had been changed: we all know that text changes come last, and developers appreciate it if I tell them exactly where they need to retype.

I think that's pretty much it, leave comments if you want to know more.


xDesign is a software user experience design group at Sun.
Follow us on Twitter : Flickr : Blog (see feeds below)


« April 2014