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.


thank you..

Posted by prefabrike on March 25, 2008 at 06:06 AM PDT #

Very nice. As a developer I would much rather build an application based on images and notes than a book of specs.

Posted by Kris Brixon on March 25, 2008 at 07:37 AM PDT #

Looks like a commercial for Adobe :-)

Posted by Henry Higgins on March 25, 2008 at 02:32 PM PDT #

Sounds good to me, yet I wonder how you manage to put all your interaction rules in this tiny right-margin space.
I used to do the same kind of specifications using powerpoint but a second document was usually necessary to write down all the possible interactions and behaviours for a single screen.

Posted by Pierre Rust on March 26, 2008 at 10:59 PM PDT #

Am I wrong, or is this a web-based mock-up that integrates detailed UI specs? Nice, but it seems like it would be more work that is implied with the editorial above, unless you're a whiz in Dreamweaver and/or already have a template. Then again, maybe I'm just a designer who tried development and found that it just wasn't for me.

I like to write, but believe visual representation renders higher efficacy. I always built wireframes powerpoint (usually from white-board sketches) that had interaction notes .. approved, these would drive functional mock-ups (also in powerpoint; using navigation links on slide). Maybe this seems like a lot of work, but I'm pretty quick in Powerpoint. ;-)

Regardless, I love your format. Thanks for posting!

Posted by on April 29, 2008 at 07:07 AM PDT #

what program are you using

Posted by willy on January 15, 2009 at 05:01 AM PST #

Jenya, am I glad you wrote this post!

I looked all over for this method description, thanks!

Posted by Anya on November 15, 2010 at 04:43 AM PST #

Post a Comment:
  • HTML Syntax: NOT allowed

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


« June 2016