[Feature Request]: Add in-context annotations and discussions

[KOTungseth]

Prerequisites

• I have searched existing issues to ensure this feature hasn't already been requested
• I have tested using the latest version of docs-builder

What problem are you trying to solve?

Elastic users currently consume documentation in a largely read-only way. When users have questions, insights, or feedback tied to specific lines or sections, they must context-switch to GitHub issues, discuss forums, Slack, or internal notes, which causes loss in precision and momentum.

This makes it harder to:

• Capture high-quality, contextual feedback on docs
• Enable collaborative learning and discussion
• Surface areas of confusion or ambiguity at scale
• Support educators, teams, and customers who want shared reading experiences

Goals

• Enable users to highlight specific text or sections and attach comments
• Support threaded discussions anchored to doc content
• Reduce friction for giving precise feedback on docs
• Improve signal quality for docs improvements
• Enable collaborative reading for teams and learning environments

Non goals

• Replacing GitHub issues or discuss forums
• Moderation workflows beyond basic controls
• Full real-time collaboration or chat

Proposed Solution

Introduce an annotation layer over Elastic Docs that allows logged-in users to:

• Highlight text and add comments
• Reply to existing annotations, for example, threaded discussions
• Control visibility, such as public, private, org/team-only
• Tag annotations, such as confusing, bug, clarification, example needed

Annotations should be stored separately from the documentation source and rendered dynamically in the UI.

Key user stories

• As an Elastic user, I want to comment on a specific sentence so I can ask a precise question.
• As a docs writer, I want to see the sections that generate the most annotations so I can prioritize improvements.
• As a team lead, I want my team to annotate docs privately during onboarding.
• As a contributor, I want to flag unclear docs without opening a full GitHub issue.

Acceptance criteria

• Users can select text and add an annotation tied to that exact location
• Annotations persist across page reloads and sessions
• Users can reply to annotations
• Annotations are associated with authenticated Elastic users
• Annotations do not modify the underlying Markdown/source content

UX considerations

• Clear visual affordance for highlighted/annotated text
• Non-intrusive UI (opt-in or toggleable)
• Discoverable, but not distracting
• Clear messaging around visibility and privacy

Technical considerations

• Annotation anchoring strategy
• Storage and indexing of annotations
• Permissions and visibility model
• Performance impact on doc pages
• Integration with existing Elastic Docs IA

Examples and Research

Inspo

• Hypothesis (web-based social annotation)
• Google Docs comments (interaction model)
• GitHub PR review comments (anchored discussions)

Alternative Solutions

No response

Additional Context

No response

How important is this feature to you?

Nice to have