Page feedback

The documentation site records page-level reactions and optional comments in the page-feedback-v1-{environment} Elasticsearch index. The API uses the feedback identifier as the document _id, so later comment submissions and reaction changes replace the same document.

The thumbs-up or thumbs-down selection writes a document with the reaction after a short debounce, so quickly changing the selection records only the final choice. The follow-up questionnaire writes the same document again with one or more structured reasons, the reason-set version, and optional details. Readers can select several reasons at once. One comment field applies to the whole submission. It keeps its value when the reader switches between Yes and No. Switching the reaction clears any selected reason that does not belong to the new reason set. The browser stores that draft in sessionStorage for the current tab and page so an accidental refresh can restore it, and clears it after a successful submit. Submitting the questionnaire flushes any pending reaction write first. This keeps abandoned questionnaires useful while ensuring the richer submission wins.

Reasons are stored in the multi-valued reasons keyword field for filtering and aggregation. reason_set_version identifies the questionnaire revision that presented the option. Display labels may change without changing their stored value. Add a new enum value when an option's meaning changes, and retain retired values so older clients and historical documents remain valid.

Reason set version 3 presents these positive reasons in display order: solvedProblem, easyToUnderstand, accurate, helpfulExamples, easyToFind, and anotherReason. The negative reasons are hardToUnderstand, inaccurate, codeSampleErrors, missingInformation, siteProblem, and anotherReason. API pages use the same stored values and reason_set_version. They pass surface="api" so labels and descriptions talk about the spec and examples instead of a product how-to.

siteProblem reports a fault in the site rather than in the content. A broken link, a control that does nothing, or a search that returns nothing belongs here, while inaccurate and codeSampleErrors stay with the words on the page.

inaccurate also covers content that describes an older version of the product. Version 3 retired outOfDate and folded it in, because a reader cannot tell a page that was never right from a page that stopped being right. Two negative sets therefore differ from version 2: it offered outOfDate and lacked siteProblem. A query that counts either one must scope itself to a version.

outOfDate remains a stored value. Historical documents hold it, and a browser running a cached bundle still submits it, so the endpoint still accepts it.

The endpoint accepts a reason only for the reaction it belongs to. A negative reason sent with thumbsUp fails validation in IsReasonValidForReaction and the request returns 400. Adding an option means adding it to PageFeedbackReason, to that reaction's list, and to the browser's reason set. Retiring one means removing it from the browser's set alone.

PageFeedbackMapping defines the mapping with Elastic.Mapping attributes. During API startup, PageFeedbackBootstrapService uses Elastic.Ingest.Elasticsearch to create or update environment-specific component and index templates. The generated context uses the API assembly version as its mapping version. Bootstrap skips unchanged mapping hashes and prevents an older API task from replacing templates installed by a newer task during a rolling deployment.

The bootstrap service and runtime gateway share one ingest channel. Feedback upserts use DirectWriteAsync and await the bulk item result before the API responds. They do not use the channel's retry overload because the browser owns the bounded retry UX. The first successful feedback write creates the concrete index from the templates.

The generated mapping disables dynamic field mapping. Fields that are not part of PageFeedbackDocument remain unindexed instead of changing the schema.

Bootstrap failures are logged and ignored in dev so the local documentation server can run without Elasticsearch. They prevent startup in staging, edge, and prod.

Runtime credentials require permission to manage component and index templates, create the environment's index, and write and delete its documents.

Template updates do not modify existing indices. For a mapping change, increment the schema version in the index name, deploy the new template, and migrate any documents that must be retained. Mixed task versions then write to separate versioned indices during a rolling deployment. The assembly mapping version is an additional downgrade guard for templates that retain the same schema-versioned name; it does not replace index versioning.