Wireframes Annotations & Documentation

Annotations, like any kind of writing, require you to know your audience. Who are these annotations for? People you should consider involving in wireframing include clients, developers, visual designers, and copywriters.

Keep in mind that each party has different expectations from the wireframes:

• Clients want to understand if the design corresponds to their business goals.
• Developers want to see what they have to support and how the product works.
• Visual designers want to see what visual elements need to be on the page.
• Copywriters want to see what they need to write.

And, most importantly, in the future, you will need to remember why you made that form element a checkbox instead of a radio button.

Annotations provide the information that static wireframes just can't. Usually, they detail how something should work on interaction. A developer, of course, recognizes that a button is interactive. But without an explanation, they wouldn't know what to make that button do. Same with copy and UX writers — they need to know the voice for the wireframe text and what information the copy should contain.

The person who creates the wireframe might experience a sort of "expert bias." You know so much about the wireframe that you might assume that everyone who looks at it will clearly understand your ideas. However, others don't have the prior knowledge that you do, and their assumptions about what something does are just assumptions. To help others, add clear information about what you want each element to do.

So, what exactly should you describe in your annotations? You can separate them into 2 main sections: content and functionality. Developers will mainly look at the functional notes and copywriters at the content. Clients, designers, and other stakeholders will look at both.

Annotations are often shown using numbers. The numbers in the wireframe should have a sharp enough contrast to stand out from the design. You can add colored circles around them and, if you like, use different colors for different types of annotations. These numbers are then listed again on the side or bottom of the wireframe with the text explanation.

In theory, any element can be annotated. However, let's not forget about the limits of people's attention. You need to prioritize what has to be annotated and what should be self-explanatory.

One of the types of elements that almost always needs annotation is conditional items, for example, a banner that is only shown to certain users but not others. Without extra information, it's impossible to guess under which conditions it shows. And if the wireframe doesn't provide this information directly, people who look at the wireframe should be able to find it in the notes.

Users think of interactive elements in terms of "What happens if I tap this?" But people involved in creating the product require more information.

When annotating interactive elements like links and buttons, ask yourself questions like:

• How many states does this element have?
• What triggers the change of state?
• What happens when users click, hover, or tap?
• How are visited links displayed?
• Where are users redirected?

Also include any other information that isn't obvious from the wireframe.

Other types of elements that require annotations are the elements that can't be fully shown in the wireframe due to space constraints. For example, you can show a couple of items in an opened drop-down menu. In the annotations, you can add the full list of items in that menu.

Annotate anything with a business, logical, or technical constraint. For example, full password requirements or the longest possible length of a username.

In cases like this, annotations should 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, justify your choices, 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 possibly hundreds of new messages, only show the first 10.”

There are 2 minds of when to annotate your wireframes. Some say you should do it as you are designing, while others claim that it's easier to do after you finish all of your wireframes.

We think that you should take the better of both worlds — annotate as you go and finalize annotations after you've finished.

Annotating as you go along and are doing the design helps you think through how something is going to work. It also helps to make sure that you don't forget how you intended something to work or what your thought process was behind a decision. When all is done, edit the annotations to make sure they are easy to understand for others.

Annotating wireframes, just like wireframing itself, is an iterative process. As a rule of thumb, your notes will get more detailed as the fidelity increases.

For example, you might start with a couple of comments about your thought process on a paper sketch. As you move into digital tools, your annotations will become more elaborate. After talking with developers, you might add more technical information.

Here are some suggestions about what you need to concentrate on at different fidelity levels:

• In sketches, add comments on ideas, personas, and scenarios.
• In low-fidelity wireframes, concentrate on initial design decisions and explore various UI options.
• In medium-fidelity wireframes, describe the functionality and layout reasoning.
• In high-fidelity wireframes, detail in-depth functionality, content and design decisions, and scenario rationale.