Writing Smart Annotations

“There are typically five audiences for wireframes: clients (internal or external), developers, visual designers, copywriters, and, most importantly, your future self.” One of the most tedious, yet necessary, tasks of an information architect or interaction designer is annotating wireframes.

Now that you’ve figured out the navigation, placed the content, and figured out page flows, it’s time to explain just what exactly that collection of “Lorum ipsum” greeking, HTML widgets, and X-ed out boxes are, how they work, and how they meet the site goals. That’s where annotations come in.

Annotations are brief notes, typically on the side or bottom of a wireframe, that attempt to describe each item on the wireframe. They have a difficult role: to speak for the wireframe’s designer when she isn’t there. In theory, when developers or clients want to know just why that link was placed in that spot, they can read the note on the document and understand not just what the thing does, but also why.

Write for your audience

There are typically five audiences for wireframes: clients (internal or external), developers, visual designers, copywriters, and, most importantly, your future self. All of these have different needs, and addressing them all in the annotations — especially given the small area that annotations typically inhabit on the wireframe — can be difficult.

Clients will want to see that you’ve incorporated the business goals they provided. Developers want to see what they have to support, and how the site or application works (and doesn’t work: don’t forget to document what happens when an error occurs). Designers want to see what visual elements need to be on the page. Copywriters want to see what they need to write. And you — the future you — need to remember why you made that form element a checkbox instead of a radio button.

One way of tailoring your annotations to multiple audiences is by creating a different set of wireframes for each. Some software, like Visio and Dreamweaver, lets you do this through layering. The IA creates a different layer of annotations for each audience, and then prints out, say, the developers’ version for their use.

Personally, I find this method to be too much effort for too little reward. Instead, I separate my annotations into two main sections — content and functionality — and display them both for everyone. Developers will mainly look at the functional notes, copywriters the content ones, and everyone else will pick and chose between both.

Since you have (at most) a long paragraph for each annotation and five audiences to write for, make sure you are applying Strunk and White’s writing guidelines: shorter sentences, clearer thoughts, no jargon.

What to annotate

There’s a tendency among new IAs to annotate everything. Don’t. Instead, be smart about what you put in the wireframe and how. The clearer you make the actual wireframe, the less you will have to explain in annotations.

For example, rather than drawing a gray box with an annotation that says it is the logo, just put the word “logo” on the gray box. For paragraphs of text, use greeking only when the paragraph’s content is obvious. Otherwise, you are better served by writing something like “This is a paragraph introducing this section. This is a paragraph introducing this section.” etc., right in the wireframe.

Things that should be annotated:

  • Any items that are conditional — when and how they should be displayed.
  • Links and buttons — what happens when they are clicked.
  • Anything that, due to space, could not be shown on a wireframe, e.g., every item on a long drop-down menu.
  • Anything with a business, logical, or technical constraint — e.g., the longest possible length of a password field.

In short, anything that is not immediately obvious from looking at the wireframe should be documented.

Show the process

Annotations have to capture not only what is being displayed (and where and when), but also why. The more you can document your thought process and the decisions you made, the easier it is to explain your work, defend it from criticism, or fix it in case you’ve made a wrong decision.

Documenting the why is the biggest challenge, especially given the space limitations. But there is a vast difference between an annotation that reads, “Show first 10 new messages” and one that reads, “Due to possible hundreds of new messages, only show the first 10.” In the second version, the reader immediately knows the reasoning behind the decision to only show 10. If there’s a change (“Oh, we’ve cut back the number of messages we’re sending to one per week”), it’s easier to adjust the wireframe appropriately.

Of course, sometimes the “why” is so obvious there’s no need to document it. There’s no reason to say, “Passwords will be starred out for security reasons.” Duh. Sometimes the reasoning is too complicated to put into an annotation, in which case I usually create a separate, attached document that shows the decision process, usually in flowchart format.

It’s okay to cross-reference other documents for support. If your business requirements state you can only store two email addresses, reference it (e.g., See Business Requirements, page 30, requirement 3). Even better, quote the requirement directly (e.g., “Only two email addresses can be stored due to estimated server space, as per Technical Specifications, page 13.”). Both of these examples are better than simply noting that only two email addresses can be stored. Three days or three years from now when someone asks why you can only have two email addresses, you’ll know.

It’s probably not a bad idea to use a small, separate area to note the documentation that affects the wireframe either: business requirements, technical specifications, use cases, etc. For one thing, it shows you’re not working in a vacuum, and lets other team members reference those documents as needed if there are questions.

If you disagree with any requirement, note that too. Perhaps two email addresses aren’t nearly enough to support how users are going to use the product. In the template I use for wireframes, there is a shaded box for issues and notes. Many times, I note where business or technical constraints have lessened the usability of a product. That way, I can either argue them now, or, if the clients or developers are reluctant to change the requirements, I can bring them up in the future, when complaints come in or another version is planned.

Another nice thing to note, process-wise, are the changes to the wireframe as you go through revisions. Your wireframe might be labeled “version 2.5,” but how does it differ from version 2.4? On my wireframe template, I have another shaded box where I list all the changes to the document from the previous version. Clients like this: it shows progress and it shows that you are actively addressing issues that have arisen during the project.

I hate to annotate

I’d be surprised to find an IA who enjoys spending his time explaining every nuance of his designs. Designing is the interesting part, not annotating. As in telling a joke, explaining takes the fun out of it. But by annotating well, you think better and design better, and a year from now, when you ask yourself, “Why did I do that?” when looking at a past project, you’ll know. And it may help you make better decisions next time.


Dan Saffer is a senior interaction designer at Ameritrade. Over the last seven years of web work, he has worked with a diverse set of clients, from Lucent Technologies to the World Wrestling Federation. He is contractually obligated to say that he won a fellowship in 1998 from the Mid-Atlantic Arts Council. He lives and works in New Jersey and is not writing a book about IA.


His portfolio and blog can be found at www.odannyboy.com.

Tackling Maintenance Projects

“Maintenance projects are distinguished by their (relative) brevity: for a majority of them, the design period will be two weeks or less, and very often only a day or two.”Most of what one reads about information architecture and interaction design work assumes several things: that you are creating the project from scratch, that you have the ability to alter anything on the screen, and that the project is free of technical or political constraints. None of these assumptions are true when you are dealing with maintenance projects.

Defining maintenance projects
Very soon after the first website went up, the first maintenance project began.

By maintenance project, I’m referring to altering an existing website or application, one that you likely had nothing to do with creating that comes loaded with technical and organizational baggage. It can be as small as adding a link to a page, or as large as restructuring the entire site. For in-house IAs like myself, these can make up the majority of work of you do. But more and more, consultants (since the collapse of the New Economy and the dearth of new web projects) are being asked to deal with them as well.

Most maintenance projects involve one of the following:

  • Adding functionality or content.
  • Removing functionality or content.
  • Revising architecture — moving content, pages, or whole sections to a different location.
  • Changing interaction — altering the way an existing piece of functionality works.

Maintenance projects are distinguished by their (relative) brevity: for a majority of them (excepting major restructuring work), the design period will be two weeks or less, and very often only a day or two. They generally require a quick assessment of the situation and decisive judgment, not to mention immediate action: rapid prototyping, wireframes, and site maps. Few maintenance projects will allow the luxury of a full exploration and design process.

A typical maintenance project goes something like this: someone has a new piece of functionality or content they want to put up on the website. The IA’s job: find the best place for it, both in the site overall and on the specific page chosen.

Server logs or a usability test (or common sense) can trigger a maintenance project by revealing that a site or an application has been structured wrong, and users aren’t able to complete their tasks (finding information, buying things, etc.). The IA’s job: fix it.

Two types of maintenance projects
There are two types of maintenance projects that I’ve taken to whimsically calling “Atomic” and “Neutron.” Each has pitfalls and challenges. I’ll discuss the rarer of the two first: Atomic.

Atomic Maintenance Projects (AMPs) are those projects that allow you to completely change how the page, section, site, or application works. AMPs usually occur when a business requirement causes you to rethink the whole “environment” around the requested change. Like an atomic blast, it can destroy things on all three tiers of development — front end, middleware, and databases. AMPs are actually regular projects in the guise of maintenance, and if you are lucky enough to convince your team to tackle one, you will likely be able to do a fuller design process than you would have otherwise.

“Often, IAs are left to wrestle with decisions that were made long before their involvement with the project; decisions that people in the company may not even like but are stuck with.”For example, let’s say an existing online form needs to capture some new sort of data (e.g., a phone number). Typically, this might just involve adding another form field. But, on examining the page where the form resides, you discover that the whole thing should be reworked: the format is too confusing, the required fields aren’t indicated, and just adding a field would make the visual design even more cramped.

This type of discovery, I should add, is not rare. I guarantee you’ll come across all sorts of things that need to be improved when you take a critical look at many web pages. What is rare is being able to convince your clients and the rest of the team that more redesign needs to be done than just adding in a form field, as everyone expected.

This, in project management terms, is called “scope creep,” and now you are the advocate of it. Sometimes this is welcomed, because a small change can reveal how poorly something is built, or show possibilities no one has thought of. But be prepared for pushback! If time is of the essence (and when is it not?), the rest of the team will want you to just pipe down and make the less-drastic change they were expecting. In other words, they will want you to make the project Neutron.

If Atomic Maintenance Projects level everything and start from scratch, Neutron Maintenance Projects (NMPs) leave the “buildings” (a.k.a. the three development tiers) mostly intact. These are much more common, because, as we’ve seen, even projects that should be Atomic aren’t because of the difficulty in convincing people that they need a more thorough treatment. Instead, the IA is left with making the best choice possible given the existing conditions.

And there’s the rub. Often, IAs are left to wrestle with decisions that were made long before their involvement with the project; decisions that people in the company may not even like but are stuck with. Or decisions they have a vested stake in keeping intact. Or decisions various forces in the company (IT, Marketing, and Legal being typical stakeholders) insist must remain, for reasons the IA may or may not agree with.

To illustrate, let’s look at the online form example. The new requirement is to collect a phone number from the user. Since the phone number could be international, you decide to create one long text field. Simple, right? Yes, until the database manager tells you that there are already two fields in the database: one for international phone numbers and one for U.S. phone numbers — and she’s not about to change the whole database structure to combine them. The Java developer doesn’t have time to write a script to send U.S. numbers to one field, and international to another. And the graphic designer mentions that by adding two separate fields, it will knock the page “below the fold,” and that’s against company policy. Oy.

It’s often frustrating to deal with NMPs, especially when you know they should really be AMPs. But there are ways to cope.

Maintaining your sanity during maintenance projects
Hardly anyone likes to do maintenance projects. They are seemingly unglamorous, janitorial chores to be dealt with in-between the bigger and better projects. And while I am not going to argue otherwise, I can provide some hard-won hints that might make them easier the next time you’re handed one.

Think inside the box. The first thing you need to do is review the requirements and figure out the best place at a high level for the change you are being asked to make. Many requirements are pretty specific about this (“We need to capture the phone number on the registration form”), others much less so (“We need to put the bios of our board members on the site”). If you have a map of the site or application, it will be handy. If not, sketch one, briefly. Find (or create) a logical space for the change.

Know the page (Part I). Once you’ve found a place for the change (if it is an existing page or screen), examine the page closely, click links, push buttons. This may seem basic, but pieces of functionality and content don’t often work the way you think they will (or the way they should). Recently, on a Neutron project, I blithely assumed that underlined items were links to related pages of “help” content. Not so: they revealed a hidden DHTML layer with a brief description of the item. You’ll often come across things that make you want to make the project Atomic during this investigation.

Know the page (Part II). If you have any technical savvy at all (and you should), find out about how the environment was constructed. Is it part of a content management system? Is any of the content dynamic? What is the application built in, Flash? C++? Java? Look at the source code if you can. Talk to the developers, the people who built it. This will allow you to know what is possible given the technical constraints, as well as alert you to any hidden problems before you start your wireframes.

Beware of hidden traps. Often, there are secret conditions and corporate political issues that you may be unaware of. These, of course, won’t be written down anywhere. Your clients just know them. The best way for you to know them as well is to cultivate a friendship with the people who know this information: the members of the development team, and especially the project manager. She can tell you that the CEO hates the word “corporate” or that Marketing is opposed to underlining links.

Pick your battles. When you do discover serious problems with a page, pause before sounding the cry to get it changed. Most importantly, consider how much impact there will be for the user and weigh it against the battle you will have to wage to get it fixed. If it will substantially make the user’s experience better and only requires you send a nice email to the Visual Basic programmer, then, by all means, proceed. If it will make a slight difference, but requires you to argue your case to the President and CEO for the next month, maybe it isn’t worth it. Here, consultants have the edge over in-house IAs. “Innies” have to measure their own reservoir of corporate goodwill, built up on the projects that have gone before and estimate how much they’ll need for projects coming in the future. “Outties” have less to lose, other than annoying those people who have hired them in the first place (and could get them more work in the future).

Down ‘n’ dirty wireframes. Unless you’ve managed to talk your way into an Atomic Maintenance Project or are creating a new page or screen, it rarely makes sense to reconstruct an existing page as a wireframe. You’ll waste a lot of time doing that, because typically you are only affecting one area of the screen. Instead, take a screenshot of the existing page, move it to Photoshop or Illustrator and make the changes in the image. Then export it as an image into your wireframe template where you can layer your annotations on top of it. These “wireframes” will be easier for the developers to understand, too.

Be considerate of visual design. On new projects, IAs often have the luxury of doing their work prior to visual design. But on maintenance projects, specifically NMPs, you are often adding things to existing pages, so even more care than usual needs to be paid to the visual design. One large, ugly button, ill-placed, can ruin a look and feel that might have taken weeks to get right and get approved. It may go against what usability gurus have traditionally been screaming at us, but I contend that an ugly solution that is functionally correct is worse than a handsome one with less-than-ideal functionality.

While handling maintenance projects are few people’s idea of a dream job, they can help sharpen your IA skills. They make you more aware of what happens in development after your designs are approved. They demonstrate how sites evolve over time, and can help you better design things that account for that reality. They make you aware of the business and technical forces that ultimately affect the design. And, best of all, they make you appreciate non-maintenance projects more.

Dan Saffer is a senior interaction designer at Ameritrade. Over the last seven years of web work, he has worked with a diverse set of clients, from Lucent Technologies to the World Wrestling Federation. He is contractually obligated to say that he won a fellowship in 1998 from the Mid-Atlantic Arts Council. He lives and works in New Jersey and is not writing a book about IA.

His portfolio and blog can be found at www.odannyboy.com.

Building Brand into Structure

Walk into any K-Mart. Then walk into any Target. You’ll see similar merchandise (substitute Martha Stewart for Michael Graves), similar target audiences, even “There is a balancing act that the IA must perform between the needs of the brand and the needs of the user.”similar prices. The difference between the stores is brand.

If you followed usability gurus like Jakob Nielsen blindly, brand would have little to no place in information and interaction design. Logo goes here, they argue. Shopping cart goes there. Users don’t want an experience, they want to find information and to do things as quickly and simply as possible.

But what if the client’s (or your own company’s) brand doesn’t support these dictums? Not every brand is utilitarian, lending itself to shopping carts and blue underlined links. And even in brands that do support these “rules,” there are differences —brand differences —that affect the display of content, site nomenclature, and users interactions with the site.

Branding 101
Whole books have been written about branding and corporate identity. A brief summary of them is this: “Brand” constitutes the essence of a company’s core characteristics —or at least the characteristics it publicly displays —and how those characteristics (or values, as they are sometimes called) are presented.

Companies can have “core characteristics.” Typically, these are one or two adjectives that define the spirit of the company. Volvo: safety. Toys “R” Us: playfulness. The US Marines: duty and honor. Many companies have a set of secondary characteristics that also inform the brand. IKEA’s core characteristics are probably affordable and Swedish; its secondary brand values might be stylish, useful, enjoyable, utilitarian, and probably a few more.

Brand as a driving force
Depending on the company, brand can drive everything from new product development to marketing to the costumes employees must wear as they serve up fries and hamburgers. Brand should be a component of every decision a company makes, from its customer service to its logistics to its letterhead to its interactive properties.

If a company (and its consultants) waits until the visual design phase to add in brand, it’s too late: it is guaranteed a flawed product. Navigation, nomenclature, and content presentation must also reflect the company’s brand. The most elegant visual design in the world isn’t going to overcome inappropriate interaction design.

Different brands: different design
What works for one site might not work for another because of brand. Amazon’s ordering process is fantastic and a model of innovative interaction design. But it can’t be directly ported over to every site because, in all likelihood, the other company’s brand would reject it like bodies reject the wrong blood type. It just wouldn’t fit. Different brands require different treatments of the same functionality.

I recently did an ecommerce B2B project for a luxury high-end retailer known for their personal service (and for their lawyers, which is why I’m not mentioning their name!). When I sat next to their customer service representatives in their call center, I was astounded at the level of service their customers asked for – and received. A pair of $400 cufflinks messengered from one of their stores that afternoon. Two hundred silver bowls engraved with the company logo and sent to two hundred separate people. A set of crystal turtles, pieces of which were scattered among five different stores, combined into one order.

It was extremely obvious that, although it contained some of the required functionality (and did so in an excellent fashion), the Amazon ordering system was not going to work for this client. Their customers were used to being able to specify the details down to the color of the ribbon that was wrapped around the gift box.

Brand can also affect how content is displayed. Because this company’s brand was all about luxury and sophistication, pages could not be packed as densely as most ecommerce sites. Only three products could be displayed on a page, and because some of those products were $350,000 US diamond necklaces, the size of the product image had to be large enough to display its quality.

I’ve found this on other ecommerce sites as well: the more sophisticated the brand and the higher the quality (and cost) of the products, the fewer products there are per page. The Gap Inc. family illustrates this well, with Banana Republic’s site displaying only a few items per page, the Gap more, and Old Navy most of all.

It’s not just in information display either. Take the Shopping Cart. It’s a very useful metaphor, nearly ubiquitous on ecommerce sites. But calling it a “Shopping Cart” simply doesn’t work everywhere. Victoria’s Secret, with their little pink and white shopping bags filled with unmentionables, would have been foolish to use the “Shopping Cart” nomenclature on VictoriasSecret.com instead of the “Shopping Bag.” When’s the last time you saw a shopping cart in a lingerie store? It simply would have been out of place. And even though it might take a user a few milliseconds initially to equate “Shopping Bag” with “Shopping Cart,” those few seconds are well worth it if the feeling you get from the site is that of Victoria’s Secret and not Yahoo Shopping.

Why do companies care? Because brand is a differentiator. In crowded marketplaces – and the web is the most crowded marketplace ever – brand is one thing that separates companies from one another. Companies with strong brands (sometimes called “brand equity”) can sell the same products as their competitors for more money. Starbucks is a case in point: they can sell a $5 cup of coffee because their customers are also buying the Starbucks experience, the Starbucks brand.

Brand vs. User
Of course, there is a balancing act that the IA must perform between the needs of the brand and the needs of the user. If you focus too much on brand, you risk turning the project into a branding exercise and not one that will meet anyone’s goals.

In some cases, this is fine: the business goal is to establish or reinforce the brand. Take a movie site I just produced for Warner Bros., 8leggedfreaks.com. Its goal is to drive people to the movie by embodying the spirit (i.e. brand) of the movie, nothing more. Users (target demographic: males 11-24) who go there might be looking for specific information about the movie (cast bios, etc.), but for the most part, they want to know what seeing the movie is going to be like. They want to know what the experience of the movie will be. A site that is all about the movie’s brand meets both the users’ and the business goals.

But in most cases, a site’s goals aren’t only to promote a company’s (or a company’s product’s) brand; they are either to provide information (content), sell things (ecommerce), or provide services (online trading, bulletin boards, gaming, etc.) – sometimes all three. How does one balance brand with users’ needs?

The golden rule is this: The brand should never hinder usability unless it would be entirely against the brand’s values to do otherwise. Sometimes, this means fewer items per page, sometimes it means calling the Shopping Cart “My Makeup Case.” Sometimes it means extra pages in the ordering process to ensure the personal service the user expects.

Although these changes may not be instantly familiar, they are, in the long run, more useful because users go to sites for a reason, and part of that reason is brand. People expect different experiences from different sites, just as you expect them from different physical places. Users who head to Christies.com to buy an expensive piece of art would probably think twice about doing so if the information design looked like eBay. They might even think they’re on the wrong site. No one minds sifting through long lists of semi-sorted items on eBay because it is part of the eBay experience based on the offline experience of sorting through junk at a flea market. But it won’t fly on a site with a more sophisticated brand.

The experience that users would have with the company in person should not be radically different than the experience they have online. The online experience can be better, more efficient, and done at three in morning in your underwear, but the traits that a company presents live should be the same ones they present digitally.

And even if the company has no bricks-and-mortar component, they still have people, and those people have personalities. The positive personality traits of those people, collectively, is their brand.

How to keep brand in mind
Brand should be an essential component when considering everything from how content is clustered to navigation to taxonomy. Here are some tips to keep your project within the company’s brand umbrella:

  • At the beginning of a project, consult the company style guide. Often, these contain clues (if not outright instructions) for using the brand in various contexts.
  • If you are consulting, visit the company’s workplace or store to get a feel for both what being an employee and being a customer would be like. If you are in-house, try to distill your knowledge about your company down to its core values. Often, you will have been bombarded by these messages already.
  • Ask about brand values. Often, the marketing people are going to be your best source for this information, and your best allies for promoting brand through structure. Explaining to them what you are doing and why, asking for their input, should head off any “brand turf” wars. If you get blank stares, it’s up to you and your team to push for a brand workshop or be stuck taking an educated guess.
  • Look over any TV commercials, print ads, or other collateral materials like brochures. Note how the company presents itself and displays its products and services. What are the adjectives that describe the work? Your designs should also reflect those adjectives.

Once you’ve done this brand exploration, you should use it to consider your designs: how does the company group its products and services in both its physical spaces and its marketing? Does it make sense? Are its customers used to it? (Be careful with this last one: even if its customers are used to it, it doesn’t make it worth porting over to the digital space.)

Nomenclature is a major area for branding. The subtle difference between say, “Company Information” vs. “About Company X” vs. “About Us” can make all the difference in the world to the feel of the site without sacrificing usability. Is the brand friendly enough to use “My”? “My Mail,” “My Account,” etc.? Or would a more impersonal “Account Information” work better?

Functionality is a particularly challenging place to address brand. One could argue that for applications, the usability of the application is paramount, and that the majority of the branding work for them should be done in visual design. Indeed, a little branding in this area goes an extremely long way. A rule of thumb is that the stronger the brand, the more you can deviate from application standards. Company X will not be able to get away with having its buttons in a odd location, but Disney might.

If your application is part of a suite of applications, it probably behooves you to make your new application conform as much as possible (and reasonable) to the other applications in nomenclature and interface design (consistent location of navigation, etc.).

The appropriate experience
One of the goals of Design with a capital D is to provide the appropriate experience for what is being presented. To paraphrase legendary adman Tibor Kalman, design is a language, not content. By being aware of brand when making your information and interaction designs, you’ll help ensure an appropriate experience that supports the overarching brand.

Dan Saffer is a senior user interface architect at Datek. He has worked with a diverse set of clients, from Lucent Technologies to the World Wrestling Federation, during the last seven years of interactive work. He is contractually obligated to say that he won a fellowship in 1998 from the Mid-Atlantic Arts Council. He lives and works in New Jersey and is not writing a book about IA.