elastic / elastic/docs-builder

Add feedback mechanism to code examples

Open
#3,743 0 comments 0 reactions 0 assignees View on GitHub
enhancement needs triage
Dominant language
C#
Stars
24
Forks
44
Avg merge
1d 7h
Merged PRs (30d)
146

Description

## Problem
Code examples across Elastic Docs can go stale or contain errors, such as deprecated syntax, wrong parameters, breaking changes not yet reflected in docs. Users currently have no direct way to flag a broken code example from the actual code block. Reports come in through indirect channels (support tickets, Slack, and page-level GitHub issues), which delays detection and fixes.

## Proposed solution
Add a lightweight feedback control to each rendered code block that allows users to report incorrect code without leaving the page.

Core flow:
1. User sees a code example that doesn't work.
2. User clicks a **Report code issue** option that appears in the code block.
3. A form captures the specific code block (auto-identified via page URL + block ID) and an optional description.
4. Submission creates a GitHub issue in docs-content-internal with page URL, code block content, and product context auto-attached for team triage.
5. SizeBot properly sizes the issue for priority, and TriageBot properly triages the issue to the appropriate team.

[Clickhouse example](https://clickhouse.com/docs#claude-desktop)
Image

### Open questions
- Should this reuse any existing feedback widget infrastructure, or is it net-new component work?
- Rate limiting / spam prevention for anonymous submissions.

### Acceptance criteria
- Every rendered code block on elastic.co/docs has a visible, accessible feedback affordance.
- Submitting a report automatically captures code block content, page URL, and product metadata.
- Submission requires no more than one required field (the "what's wrong" description can be optional if a quick "this is broken" flag exists).
- Issues are sized and routed to a repo the owning sub-team can triage.
- Feedback mechanism doesn't degrade code block rendering performance.

### Out of scope for v1
- Automated code validation/testing.
- Public-facing status of reported issues.

## Related context
Ties into "docs quality is AI quality." Broken code examples are ingested by AI crawlers and surfaced to users/agents, compounding the problem.

Contributor guide

Open the contributing guide

Research direction

Start by examining how Elastic Docs renders code blocks and whether existing feedback widget infrastructure can be reused; no specific files or tests are named. Compare behavior with the linked ClickHouse example, then verify the acceptance criteria: accessible controls, captured block and page metadata, routed issues, and no rendering-performance regression.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp
Domain
documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.