Skip to content

revamp experiment docs#1463

Draft
vaibhav-jain-exp wants to merge 2 commits intomainfrom
experiment-docs-revamp
Draft

revamp experiment docs#1463
vaibhav-jain-exp wants to merge 2 commits intomainfrom
experiment-docs-revamp

Conversation

@vaibhav-jain-exp
Copy link
Contributor

@vaibhav-jain-exp vaibhav-jain-exp commented Feb 26, 2026

Note

Low Risk
Documentation-only changes (no runtime code), with the main risk being user confusion if any rewritten examples or links are incorrect.

Overview
Reworks Experiment docs to be more task-oriented: updates overview.md with a clearer “how it works” flow and integration-path guidance, and replaces the existing quick start with a shorter 5-minute Quickstart focused on creating a remote-eval flag, installing an SDK, fetching, and checking variants.

Adds new conceptual pages for Deployments and environments and Flags vs. experiments, and significantly rewrites data-model.md and local-evaluation.md (now framed as local vs. remote evaluation) with clearer definitions, security warnings (client vs server keys; client-side local-eval visibility), and updated examples.

Updates the JavaScript SDK doc to modernize installation options (Unified SDK + CDN), streamline initialization/fetch/variant guidance, and reorganize sections around configuration, exposure tracking, consent management, and HTTP client/custom logging.

Written by Cursor Bugbot for commit 8ac1093. This will update automatically on new commits. Configure here.

@vercel
Copy link

vercel bot commented Feb 26, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
amplitude-docs Ready Ready Preview Feb 26, 2026 5:36am

Copy link

@cursor cursor bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 6 potential issues.

Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable autofix in the Cursor dashboard.

{{partial:admonition type="info" heading="Automatic exposure tracking"}}
When an [integration](#integrations) is used or a custom [exposure tracking provider](#exposure-tracking-provider) is set, `variant()` will automatically track an exposure event through the tracking provider. To disable this functionality, [configure](#configuration) `automaticExposureTracking` to be `false`, and track exposures manually using [`exposure()`](#exposure).
{{/partial:admonition}}
Access a [variant](/docs/feature-experiment/data-model#variants) from the SDK's local store. Automatically tracks an exposure event when an [integration](#integrations) or custom [exposure tracking provider](#exposure-tracking-provider) is configured.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Passive voice in variant section description

Medium Severity

Multiple newly added lines use passive voice, which the style guide marks as the highest-priority issue. Line 347 says "is configured," line 356 says "is found," and line 444 says "is called." All three are passive constructions that the active voice rule requires converting — for example, "is configured" → "you configure" or similar active phrasing.

Additional Locations (2)

Fix in Cursor Fix in Web

Triggered by project rule: Bugbot Instructions for Amplitude Documentation

## Users

Experiment users map to a user within Amplitude Analytics. Alongside flag configurations, users are an input to [evaluation](/docs/feature-experiment/implementation). Flag and experiment targeting rules access user properties.
A user is the entity being evaluated. Experiment maps users to Amplitude Analytics users through `user_id` and `device_id`. You must include at least one — remote evaluation returns a `400` error if both are null, empty, or missing.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Passive voice in user and evaluation descriptions

Medium Severity

Several new lines use passive voice. In data-model.md, "the entity being evaluated" is passive. In local-evaluation.md, "can be targeted by" (line 94) and "when a user is evaluated" (line 116) are passive constructions. The style guide requires converting all passive voice to active voice.

Additional Locations (2)

Fix in Cursor Fix in Web

Triggered by project rule: Bugbot Instructions for Amplitude Documentation

| Holdout groups | ❌ | ✅ |
| Mutual exclusion groups | ❌ | ✅ |

## Which should I use?
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Heading ends with question mark in two files

Low Severity

Both flags-vs-experiments.md and local-evaluation.md have a heading ## Which should I use? that ends with a question mark. The style guide prohibits end punctuation (periods, colons, or question marks) in headings. A heading like ## Choose the right option would comply.

Additional Locations (1)

Fix in Cursor Fix in Web

Triggered by project rule: Bugbot Instructions for Amplitude Documentation

| Environment-specific configuration | Flag |
| Showing a beta feature to specific users | Flag |
| Testing if a new design improves conversion | Experiment |
| Comparing algorithm A vs. B by measuring retention | Experiment |
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Inclusive terminology: "vs." used instead of "compared to"

Low Severity

The inclusive terminology rule says "versus" or "vs.""compared to". New body text and headings use "vs." — for example, "Comparing algorithm A vs. B" (line 82), heading "Client-side vs. server-side deployments" (line 24), and "start vs. fetch" (line 325). Page titles using "vs." in slugs are harder to change, but body text and headings can use "compared to" instead.

Additional Locations (2)

Fix in Cursor Fix in Web

Triggered by project rule: Bugbot Instructions for Amplitude Documentation


- Gradually roll out a new feature to 10% → 50% → 100% of users.
- Gate beta features behind a specific cohort or user segment.
- Create a kill switch to instantly disable a feature in production without a deploy.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Inclusive terminology: "kill switch" used in new content

Low Severity

The term "kill switch" appears in newly added content. The inclusive terminology rule flags "kill" and recommends replacing it with "stop" or "terminate." Alternatives like "emergency off switch" or "circuit breaker" convey the same meaning without using the flagged term.

Additional Locations (1)

Fix in Cursor Fix in Web

Triggered by project rule: Bugbot Instructions for Amplitude Documentation


- [Releases](https://github.com/amplitude/experiment-js-client/releases)
- [API reference](https://amplitude.github.io/experiment-js-client/)
- [npm](https://www.npmjs.com/package/@amplitude/experiment-js-client)
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changelog list items missing ending punctuation

Low Severity

The three list items in the Changelog section — [Releases](...), [API reference](...), and [npm](...) — don't end with punctuation. The style guide requires all list items to end with punctuation.

Fix in Cursor Fix in Web

Triggered by project rule: Bugbot Instructions for Amplitude Documentation

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant