Knowledge Base Articles > What Are Annotations and Why Use Them?

What Are Annotations and Why Use Them?


What Are Annotations?

Annotations are brief notes, typically on the side or bottom of a wireframe, that attempt to describe each item placed on the wireframe. They have a challenging 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 only what the thing does, but also why.

Annotations are the information provided by you, the designer, on how something on the screen should function. You can also include more details, such as design rationale, scenarios, edge cases, or examples.

The goal is to make the understanding of how and why something should work as clear as possible to anyone viewing the wireframes.

Who Are Annotations For?

"There are typically five audiences for wireframes: clients (internal or external), developers, visual designers, copywriters, and, most importantly, your future self."

- Dan Saffer

It is your responsibility to communicate the rationale of your design decisions to your client (either internal or external).

  • 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).
  • Visual Designers want to see what visual elements need to be on the page.
  • Copywriters want to see what they need to write.
  • The future you needs to remember why you made that form element a checkbox instead of a radio button.

An example of using curly braces

Callouts (curly braces here) can indicate content or copy for other consumers of the wireframes.

Why Use Annotations?

Annotations help clarify how something should work that is in a static form. Your wireframe is static. While you can indicate something should be interactive, such as a button, the developer doesn't know what to make that button do without your explanation. When looking at a static screen it is easy to make assumptions about what something does or what the content should be for that element. Help out your developer friends, and be clear about what you want an element to do.

An example of using sources for design decisions Include reasoning or scenarios to back up your decisions

How to Create Annotations

Separate your annotations into two main sections: content and functionality.

Developers will mainly look at the functional notes, copywriters the content ones, and everyone else will pick and chose between both.

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.

Annotations are often shown using numbers. The numbers in the wireframe should be a sharp enough contrast (generally with a circle around them) to stand out from the design. Then the numbers are listed again on the side or bottom of the wireframe with the text explanation.

An example of numbering annotations

Indicating what the element on the page is in each annotation is a small, but useful thing

An example of a way to include copy in wireframes

You can include the copy in multiple ways, just make sure it is clear

What to annotate

  • Any items that are conditional — when and how they should be displayed.
  • Links and buttons — what happens when they are clicked, hovered over, tapped, and visited.
  • 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.

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.

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.”

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 user flow format.

An example of showing annotations calling out different functionality

Example of annotations showing different types of functionality

When to annotate

There are two minds of when to annotate your wireframes:

  1. As you are designing
  2. After you finish all of your wireframes

Annotating as you go along and are doing the design helps you think through how something is going to work. If you annotate after you have finished all of your wireframes, you may have forgotten how you intended something to work or what your thought process was behind a decision.

Level of annotations

Like building a product or service, annotating your wireframes is an iterative process. Maybe you are in a brainstorming session and sketching on the whiteboard various ideas. You may have a few annotations to call out the functionality of what you are thinking at a first pass. Maybe you are sketching on paper and you are trying different layouts of a screen. Add a couple of comments so you know what you were thinking as you went through those ideas. As you move into digital tools, your annotations will become more detailed and laid out cleanly with your designs. When you talk with developers, you'll learn a bit more about what's needed and technical feasibility. It helps to add these notes to your annotations as well.

Level of detail:

  1. Ideation (sketch) - comments on ideas, personas, and scenarios.
  2. Low-fidelity wireframes (sketch/digital) - initial design decisions and explore various UI options.
  3. Medium fidelity wireframes (digital) - basic functionality and layout reasoning.
  4. High-fidelity wireframes (digital) - in-depth functionality and content decisions. Design decisions and scenario rationale.

Some Tips & Tricks (Q&A)

  1. What if I can't talk to the developers?
  2. Do your best to explain how you would like something to work. Don't worry about the technology itself, but the animation and functionality that is happening on the screen will need to be very clear.
  3. What if I don't have any research to back up my decisions?
  4. Best case scenario, you had research to draw from for your design decisions. If you don't, look to already solved problems, best practices, and do as much usability testing as you can.
  5. What if I run out of room on the canvas, artboard, etc. to annotate?
  6. If you have more words that don't fit on the side or the bottom of the page, don't be afraid to start a new page and keep going. Be as clear as you possibly can to get you ideas across to someone you may not be able to speak with. Each new screen has its own set of annotations and should start with a 1.

Summary

Some key points to keep in mind when doing annotations are:

  • Annotate your thoughts as you design
  • Know who your audience is for your annotations
  • Write clearly and succinctly

Julia DeBariBy Julia DeBari
Got questions or feedback? Email learn@balsamiq.com.