Wiki Contextual Discussions Beta
## Executive Summary
While the Wiki enables users to create, organize, and version-control documentation pages, as well as link them to Issues, Epics, and Merge Requests, it lacks contextual discussion capabilities on the pages themselves.
Users face significant friction when trying to discuss specific content within Wiki pages:
* Conversations happen away from the relevant context, reducing their effectiveness
* The workflow creates unnecessary context switching and reduces productivity
* Discussion threads can become disconnected from the content they reference
While we've made progress by introducing basic commenting functionality in GitLab 17.8, we need to enhance this feature to support more granular, context-specific discussions.
We propose implementing inline, contextual commenting.
#### Engineering Assessment
This builds on the work in https://gitlab.com/gitlab-org/gitlab/-/issues/465370+
1. Wiki pages use Markdown underneath. Selecting and quoting a text to start a discussion requires knowing the line number and range of the text selected. This can be determined using markdown source-maps.
2. Use the above additional information to send additional context when creating a note.
3. Allow the ability to select some text and add a start a discussion, by showing a "Comment" button in a tooltip.
#### Dependencies
- [x] We are actively examining potential dependencies from both an Engineering and Design perspective in the following Issues.
* https://gitlab.com/gitlab-org/gitlab/-/issues/523454+s
* https://gitlab.com/gitlab-org/gitlab/-/issues/509789+s
- [x] @acroitor: A dependency, potentially even blocker, might be `notes` DB table size, as contextual discussions would be leveraging existing comments functionality build on top of `notes` DB table.
##### Update
- [x] Expected `notes` table growth rate is not a blocker for the Wiki Contextual Discussions feature, after investigating the current growth rate of wiki and wiki comment trends. Since it exposes actual numbers please see the [internal discussion thread for details](https://gitlab.com/groups/gitlab-org/-/epics/16474#note_2657194651)
- [x] Aligned on the technical solution after running through 3 options as part of the [Engineering Spike](https://gitlab.com/gitlab-org/gitlab/-/issues/523454)
- [x] **Non-blocker:** In process of running a PoC based on https://gitlab.com/gitlab-org/gitlab/-/issues/523454#decision
#### **Beta Requirements**
<table>
<tr>
<th>Core Functionality</th>
<th>UX Requirements</th>
<th>Permission and Security Requirements</th>
<th>Other Requirements</th>
</tr>
<tr>
<td>
* [ ] Users can highlight any portion of text within Wiki pages
* [ ] Users can add comments directly tied to highlighted content
* [ ] Threaded discussions are available on comments made
* [ ] Users can see where a contextual comment is on a page
* [ ] Optional: Ability to edit and/or delete comments
* [ ] Optional: Ability to resolve/close comments
</td>
<td>
* [ ] Users can easily see all active discussions on a wiki page
* [ ] Comments are clearly linked to highlighted text
* [ ] Optional: Comment reactions
</td>
<td>
* [ ] Comments follow existing Wiki page permissions
* [ ] Optional: Confidential contextual comments
</td>
<td>
* [ ] Mechanism for users to report Beta issues
* [ ] Tracking of feature adoption
</td>
</tr>
</table>
#### DRIs
- **PM**: @mmacfarlane
<!--also add as assignee to this epic-->
- **EM**: @acroitor
<!--also add as assignee to this epic-->
- **UX/PDM**: @afracazo
<!--also add as assignee to this epic-->
- **Group(s)**: ~"group::knowledge"
<!--also add as label-->
- **Engineering Owner**: @johnhope
#### Initiative Driver - Product or Engineering?
- [x] **Product-driven initiatives (P1/P2/P3)** - Customer-facing features or improvements driven by Product teams that require engineering resources and commitment
- These initiatives require a Product Priority label (P1/P2/P3)
- They may also receive GTM tier labels (T1/T2/T3) for external communication
- [ ] **Engineering-driven initiatives (E1/E2/E3)** - Internal technical improvements that may not have customer-facing components
- These initiatives require an Engineering Priority label (E1/E2/E3)
- They have internal visibility only and are not externally communicated
- Examples include: technical debt reduction, infrastructure improvements, refactoring, dependency upgrades
#### Sizing and Funding (Optional)
- **Size**: L
- **Funding Status**: Funded
---
### Hygiene Guidelines
:bulb: _See additional details about this process at https://handbook.gitlab.com/handbook/product-development/r-and-d-interlock/
##### :one: Pre-Interlock
- [x] Update epic description with all relevant information
- [x] Ensure all dependencies are identified
- [x] Apply appropriate labels (see below)
- [x] Apply target delivery Milestone
- [x] Update interlock status as discussions progress (via label)
##### :two: Post-Interlock: once quarter begins
- Update health status weekly (via label)
- Document any newly identified risks or dependencies
- Link to implementation epics/issues as work begins
- Flag any scope or timeline changes immediately
<!--Apply appropriate labels:
- [ ] Section (section::dev, section::ops, section::sec)
- [ ] Stage (devops::plan, devops::create, devops::verify, etc.)
- [ ] Group (group::product planning, group::project management, etc.)
- [ ] Interlock Priority (Product labels = Interlock Priority::P1, Interlock Priority::P2, Interlock Priority::P3, Engineering labels = Interlock Priority::E1, Interlock Priority::E2, Interlock Priority::E3)
- [ ] Investment theme (Investment theme::Core-Devops, Investment theme::Security-Compliance, Investment theme::AI across SDLC)
- [ ] Platforms (platform: GitLab.com, platform: dedicated, platform: dedicated for gov, platform: self-managed)
- [ ] Subscription tier (GitLab Ultimate, GitLab Premium, GitLab Free)
- [ ] Quarter (FY27 Q1, FY27 Q2, FY27 Q3, FY27 Q4)
- [ ] Pre-interlock status label (interlock status::New/Proposal in progress, interlock status::cancelled, etc)
- [ ] Post-interlock status label (R&D roadmap status::Executing, R&D roadmap status::Completed)
- [ ] Post-interlock, once quarter begins update health weekly (health::on track, health::needs attention, health::at risk)
*For guidance on labels, see the [labels guide here](https://handbook.gitlab.com/handbook/product-development/r-and-d-interlock/#labels-guide)-->
epic