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.