Annotations 101: Explained (With Benefits, Steps, Examples, and More)

"The button is broken," says in the report. Which button? On which screen? During which phase of the moon? Without annotations, these questions float unanswered, leading developers on a wild goose chase.

Without visual clues, your bug reports become mazes of text, like reading a novel with no pictures and trying to find Waldo. Communication breakdowns become common. You describe a bug in your own dialect, developers interpret it in another, and the bug itself? It just sits there, laughing in binary.

Annotations are explanatory notes or markups added to a document to highlight important information or clarify specific sections. They can be:

• Comments
• Shapes
• Callout markers
• Underlines
• Highlights
• Notes
• Labels
• Any markups that provide additional context.

In the software industry, annotations are typically used while:

• Project reporting
• Bug tracking
• Writing Requirement Traceability Matrix (RTM)
• Bug reporting
• Sharing any project documents.

However, their benefits extend beyond software development, finding use while writing other texts, such as:

• Research papers
• Legal documents
• Student essays

Annotations can be incredibly useful while creating documents or project assets. They enable you to quickly skim through the document by highlighting noteworthy and supportive information.

Using annotations, you can:

Summarize key points

In a project report, annotations in a graph can show user engagement metrics by adding a note to mark the period with highest user retention.

Explain project requirements and perspective shifts

In an RTM, while linking a specific requirement to a design choice, annotations can explain how the design fulfills the project requirement.

Provide context clarity

In a bug report, screenshot annotations using arrows, boxes, or markups can highlight the specific area for pinpointing the bug. Additional text can also be included to describe the expected behavior of the feature alongside the observed bug.

Focus on important information

While sharing errors in the code, annotating specific lines using comments for proper explanation can help focus on crucial parts to debug or optimize much faster.

Provide supporting information

When presenting test results in software testing, annotations on the test result document can provide evidence to support the reported findings and related test cases.

Share references to previous work or resources for future works

When reporting a bug related to a previously fixed issue, annotations on the bug report can help connect to a previous bug. This can be done by putting a link (as references) for the previous bug within the annotation. This can help developers understand the context and avoid duplicate work.

Annotations can be extremely helpful when running bug tracking activities. Here are some top reasons:

Promotes shared understanding

Annotations facilitate quicker follow-ups and better feedback loops. Team members can annotate (e.g., leave comments, add resource links, attach explanatory notes) within the bug reports during bug tracking activities. This promotes shared understanding, enabling everyone to be on the same page.

Helps cut back on lengthy back-and-forth communication

Referring to the necessary information helps eliminate the need for lengthy (sometimes useless) email chains or time-consuming meetings to discuss issues.

Facilitates collaborative work during bug life cycles

Annotations make it much easier for cross-functional teams (e.g., developers, testers, and product managers) to be in sync during bug life cycles. Properly annotated bug reports enable them to work together and resolve issues very efficiently without much confusion.

Also Read: Top 10 Bug Tracking Tools: What Works Best For You?
 

Here’s a stepwise guide to capture, annotate, and report a bug:  

Step 1: Decide On What To Annotate

Start by determining the purpose of an annotation.

Example: If you have an app that’s not functioning as intended or has errors, typically, you’d:

• take a screenshot or record a video of the issue,
• annotate it,
• add relevant details, and
• send it off for debugging.

Here’s a UI issue example (missing image on the Google search page) to help show the process:

Step 2: Choose Your Bug Reporting Tool

It’s best to choose a tool that’s lightweight, convenient to use, and offers built-in annotation features.

Use BetterBugs, a free Chrome extension that you can download from the Chrome Web Store. It offers several options to create visual bug reports with annotation features.

(Note: Once you download it, create an account using your email, Gmail, or GitHub account. You can then save all your annotated screenshots as bug reports in your account to share and access them anytime.)

Step 3: Select Your Desired Mode For Capturing The Bug

Once you install BetterBugs, select the mode in which you want to capture the bug.

Step 4: Crop the Specific Area That Shows the Bug

Click the Crop option from the “Take a screenshot” feature. Drag and select the area on your screen.

Step 5: Include Annotations

Add annotations (here, marked in red) from the annotations toolbar. You can:

• Highlight the bug — using arrows, circles, or rectangles to pinpoint the exact location of the bug.
• Add explanation using text — to describe the issue and the expected behavior.
• Clarify steps — in the specific sequence. For instance, you can use numbers or arrows on the screenshot to show the steps.

With BetterBugs, you have custom annotation options for:

• Freehand marker
• Arrow marker
• Ellipse marker
• Frame marker
• Text marker
• Callout marker
• Highlight marker

Step 6: Describe the Bug

Add relevant details for it.

You can include details, such as the:

• Title
• Affected functionality
• Specific actions that trigger the bug
• Error logs in the console or network requests
• System information on which the bug occurred
• Expected behavior
• Actual Behavior

Step 7: Proofread and Share

Double-check your report for any typos or missing details. The screenshots should be clear and your annotations should be easy to understand.

With BetterBugs, once you hit the “Upload Bug” button, the annotated screenshot uploads to your BetterBugs account.

Finally, share the annotated bug report using the report link.

Using BetterBugs, you can also share the complete bug report (with the annotated screenshot) right from your browser on your project management tools like:

• Jira
• Asana
• GitHub
• Linear
• and many more.

All you have to do is to integrate your PM tools.

With every bug report you create, BetterBugs auto-attaches devtools info, such as:

• Device info
• Console logs and network requests (for any front-end issues)
• Back-end info (for Sentry)
• Meta Data
• Application State (from Local Storage Sessions)
• and much more.

• Use consistent formatting — to maintain consistency for your annotations (e.g., arrow color, text size) for maximum readability.
• Avoid cluttered annotations — by keeping annotations concise and minimal. While details are important, it’s best to avoid adding unnecessary info.
• Provide proper context — if the bug is related to a previous issue. Include references and the relevant bug report number in your annotations.
• Ensure that your annotations are the focus — and they don't obscure the bug itself.

While debugging, annotations can help:

• Gain quick contextual insights — With immediate context, annotations allow for a quick overview of a bug without extensive background information. This can significantly speed up the initial assessment and prioritization of issues.
• Get clear issue reproduction steps — Annotations can help include detailed reproduction steps for bugs. This can aid developers in replicating and retracing a bug much faster.
• Provide a targeted approach for debugging — When annotations highlight specific parts of the code related to a bug, developers can focus their debugging efforts more effectively. This targeted approach minimizes the time spent searching through unrelated code.
• Report bugs better — Tools such as Betterbugs can generate detailed reports with options to annotate way faster. This helps streamline the process of documenting to ensure that all relevant info is captured, adequately annotated, and instantly shared.

When adding annotations, avoid these common mistakes:

• Over-annotation — can make the document difficult to read. It’s best to annotate only when necessary.
• Under-annotation — makes it difficult to get enough context. Add enough explanations wherever necessary.
• Inaccurate annotations — can mislead readers. Ensure the accuracy of your annotations.
• Poor formatting — can also be a pain. Use suitable formatting and annotation elements (like shapes and symbols) to make them easy to read and understand.
• Inconsistent usage of markups while annotating — can also be a source of confusion. It’s best to use only markups that make sense. For instance, if a marker arrow works fine, there’s no point in adding text instead.

Here's a list of best practices for annotations you can borrow:

• Keep annotations straightforward — and to the point. Avoid using jargon and overly technical language, wherever possible.
• Use annotations judiciously — and only annotate when necessary to avoid cluttering.
• Provide examples — or sample code to illustrate the intended usage or behavior when applicable.
• Check annotations thoroughly — to ensure they adhere to established conventions (e.g. naming, numbering, symbol, and shape usage).
• Review your annotations — and refine them based on feedback or changes in requirements.