Originally published: Apr 04, 2009
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.
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.
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.
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:
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:
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.
Have you developed your own techniques for annotating your work deliverables? Let us know your tips and tricks, plus see what others have done, at the UIE Brain Sparks Blog.
Read related articles: