Conversation
olexii4
requested review from
a team,
deerskindoll,
gtrivedi88 and
mkuznyetsov
as code owners
|
🎊 Navigate the preview: https://6a01ebb56edde2207dab7d44--eclipse-che-docs-pr.netlify.app 🎊 |
|
Click here to review and test in web IDE: |
-525C86?logo=eclipse-che&labelColor=red){kind=icon}
ibuziuk
left a comment
ibuziuk
left a comment
There was a problem hiding this comment.
@gtrivedi88 please, review the doc structure, so that it aligns with the new policy
@olexii4 please add the Tech-preview note
olexii4
changed the title
Assisted-by: Claude Sonnet 4.6 Signed-off-by: Oleksii Orel <[email protected]>
- Fix section title levels in configuring-an-ai-provider-api-key.adoc (=== to == to follow expected sequence after = heading) - Add end-user-guide: module prefix to cross-module xrefs in ai-provider-api-key-secret-reference.adoc and configuring-ai-providers.adoc - Remove non-existent aiProviders and defaultAiProvider xrefs from checluster-custom-resource-fields-reference.adoc (AI config is ConfigMap-based, not CheCluster CR fields) Assisted-by: Claude Sonnet 4.6 Signed-off-by: Oleksii Orel <[email protected]>
| :_content-type: PROCEDURE | ||
| :description: Enable and configure AI provider support in Eclipse Che so that users can select an AI assistant when creating workspaces. | ||
| :keywords: administration, ai, ai provider, gemini, claude, configmap, ai-tool-registry, api key | ||
| :navtitle: Configuring AI Providers |
There was a problem hiding this comment.
[GLOBAL] :navtitle: uses Title Case: "Configuring AI Providers". Use sentence case: "Configuring AI providers".
This issue also occurs in:
ai-provider-api-key-secret-reference.adocline 4: "AI Provider API Key Secret Reference" → "AI provider API key Secret reference"configuring-an-ai-provider-api-key.adocline 4: "Configuring an AI Provider API Key" → "Configuring an AI provider API key"using-ai-assistants-in-workspaces.adocline 4: "Using AI Assistants in Workspaces" → "Using AI assistants in workspaces"
(Red Hat SSG: sentence-style capitalization for all titles and headings.)
🤖 RHAI docs Claude review
| :page-aliases: | ||
|
|
||
| [id="configuring-ai-providers"] | ||
| = Configuring AI providers |
There was a problem hiding this comment.
[REQUIRED] Procedure title uses gerund "Configuring". Procedure titles must use imperative form.
Suggested fix:
= Configure AI providers
(Modular docs: procedure titles use imperative verb, not -ing form.)
🤖 RHAI docs Claude review
|
|
||
| [NOTE] | ||
| ==== | ||
| To disable the AI Selector widget, delete the `ai-tool-registry` ConfigMap. Users will no longer see the AI Provider section on the Create Workspace page. Existing API key Secrets in user namespaces are not deleted automatically. |
There was a problem hiding this comment.
Two consecutive [NOTE] admonitions appear back-to-back (disabling the widget and updating the registry). Consolidate into a single NOTE or integrate the information into the main text to improve scannability.
(Red Hat SSG Structure: no multiple admonitions clustered together.)
🤖 RHAI docs Claude review
| @@ -0,0 +1,55 @@ | |||
| :_content-type: PROCEDURE | |||
| :description: Configuring an AI provider API key in Eclipse Che. | |||
There was a problem hiding this comment.
[JTBD] :description: restates the title: "Configuring an AI provider API key in Eclipse Che." Short descriptions must explain what and why — the user's job to be done.
Suggested fix:
:description: Store your AI provider API key so that it is automatically available as an environment variable in all your workspaces.
(Red Hat SSG Structure: short descriptions include what users must do and why.)
🤖 RHAI docs Claude review
| :page-aliases: | ||
|
|
||
| [id="configuring-an-ai-provider-api-key"] | ||
| = Configuring an AI provider API key |
There was a problem hiding this comment.
[REQUIRED] Procedure title uses gerund "Configuring". Procedure titles must use imperative form.
Suggested fix:
= Configure an AI provider API key
(Modular docs: procedure titles use imperative verb, not -ing form.)
🤖 RHAI docs Claude review
| :page-aliases: | ||
|
|
||
| [id="using-ai-assistants-in-workspaces"] | ||
| = Using AI assistants in workspaces |
There was a problem hiding this comment.
Concept title uses gerund form: "Using AI assistants in workspaces". Concept titles should use noun phrases that describe the topic.
Suggested fix:
= AI assistants in workspaces
(Modular docs: concept titles use noun phrases, not gerund/action phrases.)
🤖 RHAI docs Claude review
|
|
||
| The *Workspaces* page displays an *AI Provider(s)* column showing the injected AI tool for each workspace. | ||
|
|
||
| == Changing the AI tool on an existing workspace |
There was a problem hiding this comment.
[REQUIRED] The section "Changing the AI tool on an existing workspace" contains numbered procedure steps (navigate, find, click, save) inside a CONCEPT module. Procedures belong in PROCEDURE modules.
Extract this section into a separate procedure module (e.g., changing-the-ai-tool-on-an-existing-workspace.adoc with :_content-type: PROCEDURE) and include an xref from this concept page.
(Modular docs: concept modules must not contain step-by-step instructions.)
🤖 RHAI docs Claude review
| <1> Secret name is derived as `ai-provider-` + `envVarName.toLowerCase().replace(/_/g, '-')`. For `GEMINI_API_KEY` the name is `ai-provider-gemini-api-key`. | ||
| <2> Instructs the DevWorkspace Controller to mount this Secret into all `DevWorkspace` containers in the namespace. | ||
| <3> Instructs the DevWorkspace Controller to watch for Secret changes and re-mount without a workspace restart. | ||
| <4> Sanitized provider ID (slashes replaced with dashes). Identifies which AI provider this Secret belongs to. Used by the {prod-short} dashboard to detect existing keys. |
There was a problem hiding this comment.
The callout says "slashes replaced with dashes" but the source code (aiProviderKeyApi.ts) uses providerId.replace(/[^a-zA-Z0-9._-]/g, '-') — this replaces ALL characters that are not alphanumeric, dots, underscores, or dashes, not just slashes.
Suggested fix:
Sanitized provider ID (characters other than letters, digits, dots, underscores, and dashes are replaced with dashes).
🤖 RHAI docs Claude review
|
|
||
| * xref:configuring-ai-providers.adoc[] | ||
| * xref:end-user-guide:mounting-secrets.adoc[Mounting Secrets (end-user guide)] | ||
| * link:https://devfile.io/docs/2.2.0/what-is-a-devfile[DevWorkspace Operator documentation] |
There was a problem hiding this comment.
Link text says "DevWorkspace Operator documentation" but the URL (devfile.io/docs/2.2.0/what-is-a-devfile) points to a general "What is a Devfile" page. Either update the link text to match the target ("Devfile documentation"), or link to the actual DevWorkspace Operator docs.
🤖 RHAI docs Claude review
|
|
||
| * xref:configuring-an-ai-provider-api-key.adoc[] | ||
| * xref:url-parameter-for-the-ai-provider.adoc[] | ||
| * xref:mounting-secrets.adoc[] No newline at end of file |
There was a problem hiding this comment.
Missing newline at end of file. This can cause build warnings with some AsciiDoc processors.
🤖 RHAI docs Claude review
gtrivedi88
left a comment
gtrivedi88
left a comment
There was a problem hiding this comment.
JTBD follow-up — missing abstracts and feature-focused framing
Additional issues not covered in the initial review. All 5 new files are missing [role="_abstract"] and several have feature-focused framing in the intro paragraph.
🤖 RHAI docs Claude Code review
| [id="configuring-ai-providers"] | ||
| = Configuring AI providers | ||
|
|
||
| Enable one or more AI providers in {prod-short} so that users can select an AI coding assistant from the *Create Workspace* page and have the tool binary injected into the workspace editor container. |
There was a problem hiding this comment.
[REQUIRED] Missing [role="_abstract"] annotation. Every module must have a short description marked with [role="_abstract"] — it maps to the DITA <shortdesc> element and is used for link previews and search results.
Also, the intro is feature-focused: "so that users can select an AI coding assistant from the Create Workspace page" — this describes what the product does, not why the admin cares.
Suggested fix:
[role="_abstract"]
Register one or more AI providers in {prod-short} so that developers can select and use AI coding assistants when creating workspaces.(CQA / JTBD: abstracts must explain WHAT + WHY from the user's perspective, not describe product capabilities.)
🤖 RHAI docs Claude review
| [id="ai-provider-api-key-secret-reference"] | ||
| = AI provider API key Secret reference | ||
|
|
||
| The {prod-short} dashboard stores each user's AI provider API key as a Kubernetes `Opaque` Secret in the user's personal {orch-namespace}. The {devworkspace} Controller automatically mounts matching Secrets as environment variables into all workspace containers. No modification of the `{devworkspace}` spec or devfile is required. |
There was a problem hiding this comment.
[REQUIRED] Missing [role="_abstract"] annotation.
Also, the :description: uses feature-focused framing: "used by the Eclipse Che AI Selector" — describes the product component, not the admin's need.
Suggested fix:
[role="_abstract"]
Each user's AI provider API key is stored as a {kubernetes} Secret and automatically mounted as an environment variable into all workspace containers. Use this reference when manually creating or troubleshooting AI provider key Secrets.And update :description: to:
Kubernetes Secret schema, labels, and naming convention for AI provider API keys that are automatically mounted into workspace containers.
(CQA / JTBD: reference abstracts must describe what the reference item is and what it is used for.)
🤖 RHAI docs Claude review
| [id="configuring-an-ai-provider-api-key"] | ||
| = Configuring an AI provider API key | ||
|
|
||
| Configure an AI provider API key so that it is automatically injected as an environment variable into all your workspaces. |
There was a problem hiding this comment.
[REQUIRED] Missing [role="_abstract"] annotation. The intro paragraph is actually well-written ("Configure an AI provider API key so that it is automatically injected as an environment variable into all your workspaces") — add [role="_abstract"] before it.
Suggested fix:
[role="_abstract"]
Configure an AI provider API key so that it is automatically injected as an environment variable into all your workspaces.🤖 RHAI docs Claude review
| [id="using-ai-assistants-in-workspaces"] | ||
| = Using AI assistants in workspaces | ||
|
|
||
| When your administrator configures AI providers, an *AI Provider* section is displayed on the *Create Workspace* page. Selecting a provider injects the tool binary into the workspace editor container and adds it to `PATH`. |
There was a problem hiding this comment.
[REQUIRED] Missing [role="_abstract"] annotation.
Also, the intro is feature-focused: "an AI Provider section is displayed on the Create Workspace page" — describes what the product shows, not what the user gains.
Suggested fix:
[role="_abstract"]
{prod-short} supports AI coding assistants that are injected into workspaces and available from the terminal. You can select one or more AI providers when creating a workspace, and your administrator controls which providers are available.(CQA / JTBD: concept abstracts must answer "What is this?" AND "Why do I care?")
🤖 RHAI docs Claude review
| [id="url-parameter-for-the-ai-provider"] | ||
| = URL parameter for the AI provider | ||
|
|
||
| You can use the `ai-provider=` URL parameter to specify one or more AI providers to inject into the workspace. |
There was a problem hiding this comment.
[REQUIRED] Missing [role="_abstract"] annotation.
Also, the intro uses the "You can use" anti-pattern — it adds no information beyond the title.
Suggested fix:
[role="_abstract"]
Use the `ai-provider=` URL parameter to specify one or more AI providers in a workspace start URL. The workspace launches with the selected AI tool binaries injected and ready to use, without requiring manual selection on the dashboard.(CQA / JTBD: abstracts must provide information beyond the title and explain WHY.)
🤖 RHAI docs Claude review
- Sentence-case all :navtitle: values - Add [role="_abstract"] to all 5 modules with JTBD-focused text - Use imperative verb in procedure titles (Configure, not Configuring) - Use noun phrase for concept title (AI assistants in workspaces) - Fix :description: fields to explain what/why, not restate the title - Add Tech-Preview note to configuring-ai-providers.adoc - Consolidate two consecutive NOTE admonitions into one - Remove custom subheadings from procedure module; present both paths as a single numbered list with choice items - Fix hardcoded Gemini verification commands to generic placeholders - Fix callout 4: correct regex description (all non-identifier chars, not just slashes, are replaced with dashes) - Fix additional resources link: DevWorkspace Operator -> Devfile docs - Extract changing-the-ai-tool procedure into its own module and add xref from the concept page - Add changing-the-ai-tool-on-a-workspace.adoc to end-user nav Assisted-by: Claude Sonnet 4.6 Signed-off-by: Oleksii Orel <[email protected]>
Replace examples/ path with example$ family prefix required by Antora for including files from the examples/ directory. Assisted-by: Claude Sonnet 4.6 Signed-off-by: Oleksii Orel <[email protected]>
3 participants
What does this pull request change?
Adds documentation for the AI Selector Widget feature introduced in che-dashboard#1505.
Administration Guide
configuring-ai-providers.adoc) — procedure for creating theai-tool-registryConfigMap with providers, tools, and default selections.ai-provider-api-key-secret-reference.adoc) — Secret schema, labels, annotations, naming convention, and manual creation.checluster-custom-resource-fields-reference.adoc) — AI tool registry ConfigMap reference with provider and tool field tables.End-User Guide
using-ai-assistants-in-workspaces.adoc) — overview: default provider, multi-provider selection, AI Provider column in workspaces list, changing AI tool on existing workspaces.configuring-an-ai-provider-api-key.adoc) — procedure with two paths: Create Workspace page and User Preferences > AI Providers Keys tab.url-parameter-for-the-ai-provider.adoc) —ai-provider=factory URL parameter with comma-separated provider IDs.What issues does this pull request fix or reference?
eclipse-che/che#23796
Docs PR for che-dashboard#1505.
Specify the version of the product this pull request applies to
7.116.0
Pull Request checklist
The author and the reviewers validate the content of this pull request with the following checklist, in addition to the automated tests.
Validate language on files added or modifiedstep reports no vale warnings.