elastic / elastic/docs-builder

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

Open
#2,381 2 comments 0 reactions 0 assignees View on GitHub
ai-triaged ai:eng-question ai:product-question ai:ux-question enhancement needs triage stale
Dominant language
C#
Stars
24
Forks
44
Avg merge
1d 7h
Merged PRs (30d)
146

Description

### Prerequisites

- [x] I have searched existing issues to ensure this feature hasn't already been requested
- [x] 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](https://web.hypothes.is/) (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

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.