elastic / elastic/docs-content
Refresh the AI features settings page (content, role, and filename) to match the current product
- Dominant language
- No language data
- Stars
- 47
- Forks
- 261
- Avg merge
- 3d 12h
- Merged PRs (30d)
- 116
Description
## Summary
The page [`explore-analyze/ai-features/manage-access-to-ai-assistant.md`](https://github.com/elastic/docs-content/blob/main/explore-analyze/ai-features/manage-access-to-ai-assistant.md) has drifted from what it actually documents. It started life as an "AI Assistant access" page, but it has grown into the general **AI features settings** page: it now covers **GenAI Settings**, **Feature Settings**, model selection, and (via #7495) token usage tracking. The filename, URL slug, framing, and some prose no longer reflect that role.
This issue tracks a focused refresh so the page's content, structure, and filename match the current state and use of these settings in the product.
## Why
- The H1 is already **"Manage access to AI features"**, but the filename/slug is still `manage-access-to-ai-assistant` — a mismatch that's confusing to readers and authors. "Manage access" also undersells the page, which is really about *configuring* AI features, not just controlling access.
- The page accumulated content across several releases without a holistic pass, so its structure, terminology, and voice are inconsistent in places.
## Proposed work
### 1. Filename / slug + framing
- [ ] Rename to a clearer slug, for example `configure-ai-features.md` or `ai-features-settings.md` (decide on the preferred term).
- [ ] Add a redirect from the old path (see the docs-redirects skill / `redirects.yml`).
- [ ] Update all inbound links across `docs-content` (grep for `manage-access-to-ai-assistant`) and check cross-repo `://` links.
- [ ] Revisit the H1 and `navigation_title` so they match the page's actual scope.
### 2. Structure / narrative
- [ ] Reorganize the page so the narrative works for its current role — settings grouped logically (for example GenAI Settings vs. Feature Settings vs. token usage tracking), with an opening that frames the page as *configuring AI features* rather than *managing access*.
- [ ] If the page is trying to be several things at once, consider whether some content should move to (or be split into) more appropriately scoped pages, with cross-references.
### 3. Content accuracy / role
- [ ] Confirm each setting (GenAI Settings, Feature Settings, and their sub-settings) still matches the current UI labels and behavior at HEAD, across the versions the page serves (`stack: ga 9.2+`, `serverless: ga`).
- [ ] Confirm the page's content type still fits its broadened role (settings/reference vs. the older "manage access" how-to framing).
### 4. Style cleanup (from a Vale + manual review on 2026-07-30)
These are pre-existing issues, deliberately left out of #7495 to keep that PR scoped:
- **Word choice:** `choose` → `select` (the AI Assistant visibility setting, the "choosing one" cross-reference, and "Choose a default model"); "main menu" → "navigation menu" (Feature Settings intro).
- **Tense/voice:** "AI-powered features **will default** to…" → present tense ("default to…"); avoid "should power it" → "powers it".
- **Toggle wording:** prefer "turn on/off" over enable/disable for settings and toggled features ("Enable it to prevent…", "Default setting: disabled", "features are enabled").
- **Consistency:** align the two app-navigation lead-ins ("by using the navigation menu or the global search field" vs. "in the main menu or use the global search field"); align the two variants of the AI Agent/Assistant cross-reference lead-in.
- **Capitalization:** "Space's" is capitalized in the AI feature visibility bullets but lowercase elsewhere — use lowercase "space" unless matching a UI label.
- **Formatting:** the GenAI Settings (9.2–9.3) image block is missing the `:screenshot:` attribute the other three image blocks use; add it or confirm the omission is intentional. Remove trailing whitespace after the privilege link in Requirements.
## Context
Split out of #7495 (token usage tracking documentation) to keep that PR scoped to the new content. Do this as its own PR.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with explore-analyze/ai-features/manage-access-to-ai-assistant.md and review the docs-redirects skill, redirects.yml, and inbound-link search for the old slug. Compare the page with the current UI labels and behavior for stack ga 9.2+ and serverless ga. Done means the renamed, restructured page, redirect, links, terminology, and formatting are consistent and scoped in a separate PR.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100