As designers, we rely on communicating detail to our teammates and collaborators. Sometimes a picture is a thousand words, but often, we need more words and explanation to make those diagrams effective.
UIE: You've mentioned that annotation is a powerful way to add value to a deliverable. What sort of things do you annotate?
Dan: To define our terms, annotations usually refer to the words adjacent to a picture that provide further description of the design or concepts. The words should complement the picture, supplying an appropriate balance between show and tell.
Annotations come in all shapes and sizes depending on the artifact and the intent of the document. People are probably most familiar with wireframe annotations, where the author calls out areas of the screen to describe functionality not immediately discernible from the picture alone.
Words alone may provide good detail but may lack the singular clear message that a picture has. On the flip side, a picture alone may gloss over details and nuance in our design concepts. Working together, words and pictures can provide a comprehensive view.
I annotate other artifacts beside wireframes: flows and concept models, for example, can benefit from the additional detail. Like with wireframes, these annotations might capture specifics around functionality, or they might provide context absent from the picture itself. For example, I created an experience model recently that spells out the various kinds of screens available within a client's product. The model showed how users navigate between these screens, but the annotations adjacent to the model explained why these screens were important and how they fit into the product's overall strategy.
UIE: Do you have a method for it? Or is it just a brain dump? Do you try to make the annotations tell a story, with some kind of narrative? Does it depend on the goals of the document?
Knowing the document's objectives and target audience at the outset can set the tone for the annotations. If you're just trying to get the experience across to product owners, broad descriptions may be sufficient. For example:
3. Takes users to the article page.
This refers to area 3 of the wireframe, and indicates that clicking the link in area three takes users to a different page — not a huge mental leap. The annotation does add value because it clarifies the destination for the link, which may not be self-evident. Creating a document for developers, where greater detail is warranted, the annotation might include information about the number of characters or what field in the database the link text is drawn from.
One thing to keep in mind is that annotations, like the pictures themselves, will evolve over time. Your initial set of annotations may be as broad as the example, but as the product takes shape and as you learn more about the requirements, you can refine those annotations with increasing detail.
Our method is pretty straightforward. EightShapes uses Adobe InDesign to prepare documentation. One advantage to InDesign is that it allows us to separate artwork (say, a wireframe) from the document itself, so the artwork lives in its own file. We place the artwork into the document. It remains linked, so any updates to the artwork itself are reflected in the document.
Once we place artwork into a document, we then add markers — small circles with numbers or letters. Placing markers is an art in and of itself: they need to appear adjacent to the interactive element in question without obscuring it and they need to clearly indicate which element they refer to. Additionally, you need to decide the scale of your markers. You can use just a few markers to refer to broad areas of the page or you can use lots of markers to account for every element. These decisions should be driven by the overall purpose of your document, your audience, and where you are in your process.
UIE: What are some tricks for making sure the annotated documents aren't cluttered? Is there a way to prioritize the information, so the reader's eyes walk through the annotations in a controlled, organized fashion?
The conventions we use at EightShapes have evolved over years and years of experimentation, zeroing in on what works and what doesn't. For annotated wireframes, we put the wireframe on the left side of the page and the annotations on the right. We'll try to minimize the overall number of annotations on a single screen, which might otherwise look like it's suffering from chicken pox. I'd rather break a screen up into components and annotate each piece separately rather than cram lots of annotations onto one page.
Choosing an appropriate format for annotations can make them less daunting. No doubt most people use good old-fashioned prose, but we've found that adding some structure to the annotations can make them more readable. For example, for any given interactive element on a page, we will break the annotation into different scripting-like behaviors like onHover or onClick. Developers tend to like that we're trying to speak their language, and it provides some clear structure to the annotation.
We've started adorning our annotations with icons to clarify their purpose. Annotations might describe business logic, editorial guidelines, or display conditions, among others. Each of these functions has a unique icon to help differentiate them on the page.
UIE: What are some pointers for designers, when annotating their deliverables?
The best advice I can give designers is to design their documents as they would a web site or product. Think about the target audience and what's going to be most valuable to them. A few pointers:
- Keep annotations jargon-free: Imagine that people will be reading this document without the benefit of your presence. The annotations and pictures need to stand on their own two feet. On the one hand providing enough detail and context, and on the other avoiding things that might obscure their meaning. Abbreviations and "insider" language prevent understanding.
- Balance words and pictures: It can be tempting to rely too much on one or the other, especially if you feel your strengths lie in, say, drawing a picture. Too much picture and readers might not get enough functional details or context. Too much text and readers might not get a sense of the overall experience.
- Adhere to a theme: For any given page in the document, think about the point of the page and how it contributes to the purpose of the overall document. If you're preparing annotated wireframes, it would be a mistake to say that the point of the page is to describe the functionality of a screen. Be more specific: are you describing business logic? editorial guidelines? error scenarios? Once you've zeroed in on a theme for the page in the document, you can be ruthless about which annotations to include. Such an approach might require your creating multiple sheets in the document to address different aspects of the design. For example, one page deals with editorial guidelines and another deals with application logic.
UIE: Are there some tools that do a better job than others?
Rather than take that bait, I'm just going to say no. Ultimately, the "best" tool is the one you feel most comfortable using. That said, everyone should always be open to exploring applications they haven't tried before. That exploration alone, makes us better designers. Expertise in various applications makes us more marketable.
If you have the opportunity to explore different applications, or you're looking to standardize for your team, you should consider these criteria:
- Collaboration: Our research shows that different teams have different models for collaborating with each other. Some remain fairly siloed in their approach while others pass files around constantly. Some work on individual files which then get assembled into a final document, and some create assets that get reused on later projects. Consider the collaboration culture of your design team before committing to any particular tool as the tool will have a substantial impact on how you collaborate.
- Portability: One reason we like Adobe InDesign is that it's cross-platform, Mac and PC. Design teams that have users of both operating systems don't have to worry about whether files from one will open on the other. Another nice thing about the Adobe suite is that assets from one application play nicely with other apps, and they all play pretty nicely with PDF. These factors might be relevant even for smaller teams.
- Flexibility: Neither collaboration nor portability are specific to annotations. The fact is that our tools need to do lots of things, not just annotate artwork. (Though, I wonder what would happen if I had one tool for artwork, one tool for annotations, and one tool for compiling those into a deliverable.) As a designer, I'm perpetually dissatisfied with my work — occupational hazard, right? Even after handing in a deliverable, I wonder if there was a better way to express my ideas. Good tools help enforce standards but also enable experimentation. Good designers know their tools inside and out so they know when to stick with a standard and when to experiment.
Hear Dan Speak at the UIE Web App Summit
It's no surprise that Dan's full-day workshop, Communicating Design: Essential Deliverables for Highly Effective Teams, is one of the most popular at the upcoming UIE Web App Summit. More than ever, teams need every tool they can get to be effective and Dan's toolbox is the envy of us all. Find out more about his workshop and the complete Web App Summit agenda.