Contextual Discussions on Wiki Pages (#16296) · Epics · GitLab.org

Contextual Discussions on Wiki Pages

## Background 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. ## Current Problem 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. ## Proposed Solution: Contextual Comments We propose implementing inline, contextual commenting similar to our existing code review functionality. This would allow users to: 1. Highlight specific portions of text within Wiki pages 2. Add comments directly tied to the highlighted content 3. Create threaded discussions around these contextual comments 4. Maintain all context and discussion history within the Wiki page itself ## Implementation Path * Beta (two core items) * Start with implementing Wiki Nav Content, designs in the following Issue: https://gitlab.com/gitlab-org/gitlab/-/issues/557576+ * Then proceed to the implementation of the [Product Design Spike Issue](https://gitlab.com/gitlab-org/gitlab/-/issues/509789) designs, which implements the contextual comments approach in the right-hand sidebar * GA (one core item) * Edit Mode: https://gitlab.com/gitlab-org/gitlab/-/issues/560758 (edit mode will only be useful once we have contextual comments done) ## Success Criteria The implementation should: - Support text selection and highlighting anywhere within Wiki pages - Enable comment threads tied to specific text selections - Maintain threading functionality for replies and discussions - Preserve comments across page revisions - Include notification capabilities for relevant stakeholders ## Target Use Cases I've taken into account the [GitLab Personas ](http://handbook.gitlab.com/handbook/product/personas/)when considering the target use cases for contextual comments on wiki pages. * **Documentation Review for Cross-Functional Teams (Parker + Delaney + Presley)** * Parker (Product Manager) can highlight specific feature requirements in technical documentation to get clarification from Delaney (Development Team Lead) about feasibility and timeline estimates, while Presley (Product Designer) comments on user flow descriptions that need design specifications. This eliminates the scattered feedback across Slack, Issues, and meetings, keeping all context-specific discussions anchored to the exact documentation sections they reference. * **Knowledge Base Maintenance and Accuracy (Sasha + Priyanka + Janell)** * When Sasha (Software Developer) encounters outdated deployment instructions or incorrect configuration examples in runbooks, they can comment directly on the problematic text rather than creating a separate Issue that loses context or commenting generally at the bottom of the page. Priyanka (Platform Engineer) and Janell (Enablement Advocate) can respond with corrections and updated best practices, creating a living audit trail that helps maintain accurate internal documentation and prevents future confusion. * **Compliance and Security Review Workflows (Amy + Cameron + Delaney)** * Amy (Application Security Engineer) can flag security concerns on specific code examples or architectural decisions documented in wiki pages, while Cameron (Compliance Manager) highlights sections requiring audit evidence or policy adherence. Delaney (Development Team Lead) can see all compliance and security feedback in context, enabling faster resolution without constantly jumping between the wiki, security tools, and compliance tracking systems. ## [Spike Results](https://gitlab.com/groups/gitlab-org/-/epics/17013) [Engineering Spike](https://gitlab.com/gitlab-org/gitlab/-/issues/523454) and [Design Spike](https://gitlab.com/gitlab-org/gitlab/-/issues/509789) * The primary engineering challenge is how to anchor the discussions within the wiki page text that can be rendered in HTML, edited in Rich text editor, plain text editor and manipulated offline and pushed using git. * **Option 1** Adding anchor nodes (`<comment id="123">Lorem ipsum</comment>`) to the text as it's stored in Git * **Option 2** Adding anchor nodes to a copy of the text stored in the DB * **Option 3** Adding context metadata to the comments with position information `{ start: 234, end: 893 }` Each option comes with unique [challenges](https://gitlab.com/gitlab-org/gitlab/-/issues/523454#note_2633208448). * We [aligned](https://gitlab.com/gitlab-org/gitlab/-/issues/523454#note_2645977282) on pursuing option 3 — adding comment Metadata — due to its flexibility and despite a relative implementation complexity.  > [!important] > > This page may contain information related to upcoming products, features and functionality. It is important to note that the information presented is for informational purposes only, so please do not rely on the information for purchasing or planning purposes. Just like with all projects, the items mentioned on the page are subject to change or delay, and the development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc.

epic