What is visual feedback?
Visual feedback lets readers report a documentation problem with page context, a comment, and an optional annotation that shows exactly where the problem appears.
Visual feedback lets a reader show you where a problem appears instead of describing the location from memory.
A report can include the page, a written comment, and an optional screenshot with an annotation pointing to a specific code line, diagram, table, button, or other page element.
For example, a developer might highlight the webhook-signature line in an API example and write:
I cannot tell where this signature should be added.
The documentation team now knows which page, example, and line to inspect.
PushFeedback visual feedback combines page context, comments, and optional screenshot annotations in the same report.
Use annotations when the exact location matters
Not every feedback report needs a screenshot.
A comment may be enough when the reader can clearly explain the problem from the page itself. An annotation is more useful when pointing to the exact element removes ambiguity.
| Visual feedback helps when | A comment may be enough when |
|---|---|
| A specific code line looks wrong | The whole page is missing a prerequisite |
| A diagram or table cell is unclear | The reader can name the missing information clearly |
| A button, link, or UI label does not match the instructions | The problem applies to the page as a whole |
| A layout or rendering problem appears in one location | The exact location does not affect what the team needs to inspect |
| A screenshot in the docs shows the wrong control | The reader only needs to explain the task they could not complete |
Use the lightest feedback method that gives the team enough context to investigate.
Understand the difference between ratings, comments, and annotations
These feedback types answer different questions.
| Feedback type | What it tells you |
|---|---|
| Rating | Whether the reader found the page helpful |
| Comment | What the reader was trying to do or what went wrong |
| Screenshot | What the page looked like when the reader submitted feedback |
| Annotated screenshot | Which specific part of the page the reader wants the team to inspect |
A rating helps identify a page worth reviewing. A comment adds the reader's explanation. An annotation becomes useful when the location itself matters.
For a page-level rating workflow, see how to use a helpfulness widget in docs.
Ask for enough context, not more than you need
A useful visual feedback report usually needs:
- the page where the report was submitted
- a short description of the problem
- the reader's task when it helps explain the issue
- an annotation only when pointing to the exact element adds useful context
Do not require a screenshot for every report.
Screenshots can also capture information the reader did not intend to share. If you enable visual feedback on signed-in or sensitive pages, review the screenshot and privacy settings that apply to your project.
For more on annotated screenshots, see screenshot annotation.
Review the report before deciding what to fix
Visual feedback tells you where to investigate. The team still needs to decide what the problem actually is.
A marked API example might contain an outdated parameter. It might also accurately document the intended behavior while the live product behaves differently.
Check the current documentation and product behavior before assigning the fix.
For API-specific reports, see how to collect actionable feedback on API reference documentation.
For the broader feedback workflow, see how to collect and use documentation feedback.
Frequently asked questions
Is visual feedback the same as a screenshot?
No. A screenshot captures the page state. Visual feedback combines that context with the reader's report and can include an annotation showing the exact element they are referring to.
Does every documentation report need an annotation?
No. Use an annotation when pointing to a specific element makes the problem easier to understand. A normal comment is enough when the reader can already explain what needs attention.
Can visual feedback replace bug tracking?
No. Visual feedback helps collect and understand the initial report. If the investigation confirms work that needs to be tracked, move it into the team's normal issue or task workflow.
When is visual feedback most useful for documentation?
It is especially useful for code examples, diagrams, screenshots, tables, UI instructions, and layout problems where the exact location is difficult to describe in text.
Use visual feedback when pointing is faster than explaining
Start with a comment and page context. Add an annotation when showing the exact location makes the report easier for the team to understand.
Create a PushFeedback project to test visual feedback on one documentation page.