elastic / elastic/docs-builder
[Feature Request]: Add in-context annotations and discussions
- 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
Assessment
This issue has not been assessed yet.