Design Basics: Annotating Your Work
Why, when, & how to provide useful annotations with your design deliverables
As Wayfair continues to build out our growing design org, we’ve been crossing t’s and dotting i’s on our training materials for entry-level and experienced designers alike. We thought it might be useful to publish these guides to Medium as well!
What are annotations?
Annotations are brief, written explanations provided with design deliverables in order to define & describe aspects of the design. They’re paired with numbered labels on the design itself to visually map each description to the relevant part of the design.
The primary purpose of annotations are to explain aspects of the design that the recipient may not otherwise perceive, understand, or account for during implementation. They may be used differently from project to project, but they should always be serving this goal.
Different from project to project…?
Annotations aren’t always paired with the same kind of deliverable.
We often hear about them in the context of wireframes, but that’s sort of just a byproduct of their historical usage. Simply put: if writing & distributing some notes with your design will help your cross-functional partners better understand it, then have at it! You could be handing off a user flow annotated to explain certain happy paths & edge cases, wireframes annotated to explain functionality or conditional states, or high-fidelity mocks of static pages that use annotations to convey specific style requirements and asset locations. All of these are completely valid uses for annotations.
They’re not always necessary.
All those examples of deliverables I just mentioned? You can also have projects where these same deliverables do not require annotations at all. More on that below in the “When it’s not useful” section.
The format and delivery of annotations can change from project to project.
If they’re short & sweet and light on technical specifics, you may want to just include them right alongside the visuals, baked right into the Invision, PDF, etc. If they’re verbose & very technical, you may be better off moving them into a separate document. Having those numbered labels on the design that correspond to the annotations provides this kind of flexibility.
When during the design process should you annotate?
While waiting until designs have been 100% approved is the ideal (so you don’t end up having to revise your annotations based on changes to the design), that’s not always possible due to parallel workflows, and sometimes there can be a benefit to annotating a little bit earlier in the process.
When your deliverable is roughly 80% ‘complete’, that’s a good time to consider annotating. Prior to that, designs may be too ‘subject to change’ to make annotating valuable, but once you’re in the final rounds of revision, annotations start being really helpful.
…Why 80%?
While you should certainly be communicating with stakeholders and developers throughout the entire design process, sometimes this 80% mark is the point at which your conversations will move over to email or slack and other business stakeholders get looped in. Written explanations can help expedite those conversations by providing context to a broader distribution list, without requiring additional meetings.
In my own experience, this also tends to be the point at which my product manager and developer(s) start to really think about the design as a collection of discrete, bite-sized engineering tickets. If they’re able to start referring to “Annotations 1.1–1.3” when scoping and entering those tickets, that makes everyone’s lives a lot easier.
When are annotations useful?
If your project meets any of the following criteria, consider annotating your deliverables…
There are elements of the design that are not totally obvious from the visuals alone.
- Hidden content — What else is in that dropdown?
- Interactivity — What’s that button/link do?
- Unrepresented constraints — Is there a max-width on this card/field/button?
- Conditional stuff — Are some elements different based on user type, product type, user interaction, etc?
The project itself is a non-trivial effort to build.
- Are we talking about a new feature?
- Are multiple developers working on this?
You don’t know exactly who the audience for your deliverables will be.
- Don’t know exactly which developers will be working on it?
- Does your PM need buy-in from Merch/Category folks with whom you haven’t had much interaction?
When aren’t they useful?
While annotations are helpful in providing clarity and definition to an otherwise complex or ambiguous project, some projects start out…pretty clear and well-defined! If we’re talking about a fairly minor ticket being implemented by a developer with whom you work really closely, and you’ve got zero stakeholders outside your immediate team, then feel free to keep it lean and skip the annotations.
A quick step-by-step guide to annotating…
Step 1: Determine what format you’ll be using for your annotations
Are you going to put ’em right on your Sketch artboard? In a separate Google Doc? The world is your oyster, and you can change your mind later if you need to.
Step 2: Determine what elements you’ll be providing annotations for, and label them in your design.
These should be the elements that fit the criteria mentioned above in “When are annotations useful?”
Step 3: Write out your annotations!
They should contain…
- An ID that corresponds to the label you placed on the design.
- A succinct title that confirms at a glance that this is the correct annotation (i.e “Password Field” for the password field annotation)
- A brief description of: functionality, or user expectations, or style requirements, etc.
- When presenting alongside the design: nearly every article on the internet will put them/advise you to put them on the right. I like ’em on the left. You decide.
Step 4: Make them available to the intended audience!
If you’re using a document separate from the designs to deliver annotations, there’s always a chance that document doesn’t survive the journey once folks start passing around your work; whenever possible provide a hotspot, link, etc to your annotations from within your design deliverables.
Things to watch out for…
Writing annotations is NOT a substitute for speaking with your developers.
In fact, you’d be well-served by using them as the agenda for a touch-base with your cross-functional team, where you walk through the annotations in person and solicit questions & feedback. With really granular, technical annotations (what tend to be referred to as ‘functional specifications’) you may see these copy/pasted directly as the acceptance criteria on engineering tickets, so make sure everyone is aligned as early as possible!
Developer says: “Oh, I didn’t read the annotations.”
As sure as the sun will rise tomorrow, you will be asked questions that you explicitly addressed in your annotations.
First: Relax. It happens. We’re all human.
Second, keep that link handy and respond with the annotations, citing the specific label they can refer to for their answer.
At Wayfair, we communicate a lot on Slack and for larger initiatives, we’ll have a project-specific channel. That’s a great place to “pin” the annotations and other design deliverables!
Frequently Asked Questions…
1. What kind of stuff should I include in annotations? How do I avoid getting too specific or being too vague?
The answer for both of these is talk to your developer; make sure that you two are fully aligned on what level of specificity is appropriate, and write no more than that. Knowing your audience is important and anticipating the questions they may have is a great way to determine what needs to be annotated, but as product designers, we tend to work with a bunch of different teams and “too specific” / “too vague” will vary from person to person. If you have to pick one person for whom the annotations are 100% crystal clear, make that your developer.
2. What if stuff changes during development? Do I have to go back and update these?
First: annotations, just like your other deliverables, should have a date on them somewhere that conveys when they were last updated. Beyond that, if you want to make minor changes after hand-off, do it up. It’s great having a 100% accurate set of annotations and designs to refer back to, whether it’s to the benefit of someone down the road working on the next version/iteration of the project, or simply to act as a point of reference for the expected in-production functionality. But if it gets unwieldy to maintain because a lot of stuff is changing in development…that’s what the “last updated:” date is ultimately there for.
That said: if this is happening a lot, it’s worth discussing in your scrum team’s retro. Alarm bells should go off if designs & annotations are going stale before development has even finished. There are a bunch of different reasons this happens: edge cases get missed, the scope of the project gets trimmed down, etc. It happens. Whatever the reason, it’s a learning opportunity, so make sure you talk about it.
3. When you say “annotate your deliverables”….which deliverables are you talking about? I have multiple. Do I annotate them ALL? That seems stupid.
Primarily, this is meant for whatever deliverable your engineer is referring to during development. But it’s up to you; maybe the user flow you made is just a stepping stone on the way to full-on designs BUT you know it’s going to get passed around to every stakeholder under the sun for feedback — probably worth annotating it if you can provide some additional context by doing so!
Conclusion
Hopefully this article sheds some light on the value of providing annotations and gives you some insight on how to make use of them in your own work!
If you found this useful, or if you’ve got your own tips & tricks, let’s chat in the comments!
