Skip to content

docs: correct factual errors and remove stale screenshots - #2373

Open
Suneha Bose (bosesuneha) wants to merge 9 commits into
Azure:mainfrom
bosesuneha:docs/factual-corrections
Open

docs: correct factual errors and remove stale screenshots#2373
Suneha Bose (bosesuneha) wants to merge 9 commits into
Azure:mainfrom
bosesuneha:docs/factual-corrections

Conversation

@bosesuneha

@bosesuneha Suneha Bose (bosesuneha) commented Aug 6, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

PR 3 of 3. Stacked on #2372, so it shows the earlier PRs' commits until they merge.

Two commits.

1. Factual corrections

Every claim was verified against package.json, src/, or resources/ rather than taken from the existing text.

Page Was wrong
merge-save-kubeconfig Documents two commands as ours. Neither is in contributes.commands; both come from ms-kubernetes-tools.vscode-kubernetes-tools, an extensionDependency
draft-integration Says Draft Dockerfile and Draft Deployment are in the Command Palette. Both are registered in src/extension.ts:147-148 with no contributes.commands entry, so they are unreachable. aksDraftValidate was undocumented, and the pinned Draft version was never stated
container-assist-github-workflow All five Action versions stale: checkout v4, login v2, use-kubelogin v1, aks-set-context v4, k8s-deploy v5. Actual: v7.0.0, v3.0.0, v1.3, v5.0.0, v6.0.0
container-assist-github-workflow, container-assist-integration Document an "Annotate namespace" step. No template contains it, and workflowTemplate.test.ts:223 asserts it is absent
container-assist-azure-resources "9 role assignments" summed two mutually exclusive paths. Maximum is 5
aks-diagnostics Two detector titles renamed, one reworded, Storage missing
run-kubectl-command, k8s-api-health-points Labels did not match kubectl.ts: "API Resources" is "Get API Resources", "Get Node" is "Get Nodes", health checks end in "Check", and Get All Events was missing. Both pages now show the kubectl command each runs
argocd-gitops-integration Apply runs with --validate=false, omitted. The Copilot integration is an Azure AI Agent plugin, not a chat skill
telemetery.md, README.md telemetry.enableTelemetry was deprecated in VS Code 1.61; the setting is telemetry.telemetryLevel set to off

2. Screenshot cleanup

Deletes 23 images. 100 down to 77, 12M down to 9.6M.

14 were referenced by no page. Nine were already dead; five were orphaned by the features.md rewrite in #2372.

9 were still referenced but show the classic cluster menu. The default switched to the grouped menu in #2168 on 2026-05-30, and every one of these was last touched before that, the newest in 2025-07-28. They pointed readers at menu items that are no longer there. The text breadcrumbs added in #2372 replace them, and unlike screenshots those are validated by docs:check.

Webview and result-panel screenshots are kept: they show output that text cannot convey.

A checker bug this surfaced

docs-check only parsed markdown ![](...) image syntax, so three images referenced with raw <img> tags in aks-plugins-github-copilot.md were reported as orphans. I deleted them, then cross-checking against lychee showed 3 broken links where docs-check showed none. Restored, and the parser now handles <img src> and <a href>. That fix is in #2371.

Verification

docs:check 0 errors and 0 orphan warnings, lychee 0 errors, mdbook build clean. The two tools now agree, which they did not before the parser fix.

Remaining: 21 coverage warnings for undocumented commands, plus the missing 2.2.0 and 2.3.0 what's-new pages and the CI gates. Those are follow-up work, not in this PR.

3. Release notes (added)

Release notes stopped at 2.1.0 while the extension shipped 2.4.0, so the three releases that added the Argo CD default-on flag, the Kickstart agent and the Container Assist changes had no reader-facing notes.

Replaced whats-new-2.1.0.md with whats-new-2.4.0.md covering 2.2.0 → 2.4.0, per the release-pr skill's convention of keeping only the current release's file. Updated SUMMARY.md and release.md.

Content is derived from git log 2.1.0..2.4.0 — please check the highlights read the way you want them to.

4. Telemetry disclosure (added)

This is a privacy document, so the gaps matter:

Issue Evidence
Per-message webview telemetry undisclosed BasePanel.ts:162-164 emits an event per webview message as <panel>.<action>
clusterCreationSuccess filed under Copilot handlers CreateClusterPanel.ts:300 picks the plain command event for the normal Create Cluster flow
Application Insights transport unmentioned reporter.ts uses @vscode/extension-telemetry with meta.aiKey
README.md and telemetery.md disclosed different data README listed only "which commands are executed"

Added an explicit "what we do not collect" section and a pointer to the Container Assist AI data flow page, which is a separate flow from telemetry. Also removed the duplicated # Telemetry / ## Telemetry heading pair.

6. Smaller corrections (added)

  • Container Assist was titled "Alpha Preview" while SUMMARY.md, the feature index and the command titles all say "Preview" — three labels for one feature.
  • book.toml declares the mdbook-toc preprocessor but no page used the marker, so the build depended on that binary for nothing. Added <!-- toc --> to the two pages long enough to need it (338 and 200 lines).

Deferred to a follow-up PR

The 1200-line cap is the binding constraint; this PR lands at 1104. Left for a PR branched from main after this stack merges:

  • Kickstart feature page — still undocumented apart from generated table rows, and aks.kickstartEnabledPreview defaults to false, so it is undiscoverable without docs.
  • Expanding the 9 remaining stub pages to a standard template.
  • Prose for the commands docs:check still reports as uncovered (Quick Actions, Attach ACR, permission checks, OIDC setup, cluster filter, Fleet properties).

Verification

docs:check 0 errors (warnings 32 → 17), docs:reference:check up to date, all SUMMARY entries resolve, 0 broken local links, 0 pages missing from SUMMARY, Prettier clean.

Note on wording

The user-facing pages were rewritten to read from the reader's point of view. The originals described the extension from the perspective of the people building it: "gated behind a feature flag", "it contributes two commands", "the scaffolder emits", "the SDK classifies it as other", and event shapes like createCluster.createClusterRequest in the privacy page.

The "feature flag" sections were the clearest case — each gave instructions for enabling a setting that is already on by default, so the one decision a reader actually has (turning it off) was the one thing not documented. Same on the menu page, which documented the default layout as opt-in and referred to "the new menu", a comparison a new reader cannot make.

The DevHub removal is deliberately not in the release notes: that code was orphaned with no contributes.commands entry, so no reader can have been using it.

Contributor docs moved out

CONTRIBUTING.md, its book copy and the development page target contributors rather than users, so they moved to #2382 to be reviewed by the right people. That also keeps this PR at 1104 lines, with room for review feedback.

@bosesuneha
Suneha Bose (bosesuneha) force-pushed the docs/factual-corrections branch 3 times, most recently from e78c3ba to 963777e Compare August 12, 2026 00:10
@bosesuneha
Suneha Bose (bosesuneha) marked this pull request as ready for review August 12, 2026 00:23
@bosesuneha Suneha Bose (bosesuneha) mentioned this pull request Aug 12, 2026
Open
@bosesuneha
docs: fix broken links, restore missing Development page, drop duplic…
a4c2edc 
…ate copies

The published Development section rendered as a bare heading because
SUMMARY.md linked to ./development.md, which did not exist. mdBook's
create-missing default silently generated an empty stub instead of failing,
so this went unnoticed. Add the page and set create-missing = false.

Three pages under docs/ were stale forks of their docs/book/src/
counterparts, and docs/README.md linked only to the forks:

  docs/webview-development.md  missing the Custom UI Elements section
  docs/package-scripts.md      missing the Local VSIX Sharing section
  docs/maintenance/README.md   last updated 2021; missing the pinned
                               third-party versions section entirely

Delete them and rewrite docs/README.md as an index into book/.
The release skill instructed maintainers to mirror releasing.md into
docs/maintenance/README.md, which is why that fork stayed alive; update it
to name book/src/ as the single source of truth.

Also fixed:
- ../package.json and ../webview-ui/ links resolved outside the book
- dev-webview / build-webview are not real npm scripts (dev:webview,
  build:webview)
- webpack-ui typo for webview-ui
- SUMMARY.md nav labels disagreed with the pages' own titles
- bin/ ignored; make -C docs/book build writes mdBook binaries to the repo
  root because the Makefile uses $(PWD) rather than $(CURDIR)
@bosesuneha
docs: add generated reference section and fix feature navigation
ebb9f49 
Adds reference/ pages generated from package.json by
scripts/generate-docs-reference.js, carrying a DO NOT EDIT header: commands
with their menu placement, settings, and pinned versions.

SUMMARY.md listed show-properties-azureportal-start-stop.md four times and
inspektor-gadget.md twice, so three sidebar entries led to a page that did not
match the label clicked. Collapsed to one entry each; no URLs change.

features.md was a stale 2.1.0 release spotlight that linked to 2 of its 25
feature pages. Rewritten as an index. This orphans 5 classic-menu screenshots,
removed in a later PR.
@bosesuneha
docs: correct cluster menu paths in feature guides
502cbcf 
aks.simplifiedMenuStructure has defaulted to true since Azure#2168, grouping cluster
commands under Develop & Deploy, Troubleshoot & Diagnose, and Manage Cluster.
The guides still described the classic flat menu, so readers were told to look
for items that are now one level down.

Paths come from the generated menu reference, not from reading the UI, and are
written as "Right-click your AKS cluster > Submenu > Command" so docs-check can
validate them. Guides describe the default menu; the classic layout is covered
once, in simplified-menu-structure.md.

Also corrected:

- aks-compare-cluster is on the subscription node, not the cluster node
- "Managed Cluster Operations" is the classic label; the default is
  "Manage Cluster"
- the KAITO submenu is "Deploy a LLM with KAITO", not "an LLM"
- container-assist pointed at AKS: Run Container Assist (Preview), which has no
  menu contribution; replaced with the three real commands
- inspektor-gadget claimed the command had moved to the main context menu,
  which described the classic layout and was backwards
- "Abort Last Operation" is a webview action in ClusterPropertiesPanel.ts, not
  a command, so it is no longer listed as a menu operation
- simplified-menu-structure.md advised keeping the default false while stating
  above that it was true

merge-save-kubeconfig.md is left alone: those commands belong to
ms-kubernetes-tools.vscode-kubernetes-tools.
@bosesuneha
docs: normalise heading levels
3eb3edb 
Mechanical. Only the number of leading '#' changes; heading text is untouched,
so every anchor still resolves.

17 pages had a broken hierarchy: 12 jumped from '#' straight to '###', and 5
had no top-level heading at all. Each file's levels were remapped to a
contiguous sequence starting at 1, and where that left more than one h1 the
later ones were demoted so each page has a single title.

Sidebar labels come from SUMMARY.md so navigation was unaffected, but skipped
levels are a problem for screen readers.
@bosesuneha
docs: fix doubled AKS prefix in palette, drop deprecated workflow page
8a22c01 
Two commands set both `category: "AKS"` and an `AKS: ` prefix in their
title, so VS Code rendered them as "AKS: AKS: Launch Kickstart Agent"
and "AKS: AKS: Configure Kickstart Cluster" in the Command Palette.
VS Code composes the palette entry as `category: title`, so the prefix
belongs in exactly one of the two. Dropped it from the titles.

No localized `package.nls.*.json` files exist and `l10n/bundle.l10n.json`
does not carry these strings, so no translations are affected. The
rendered palette text is unchanged from what the docs already describe.

`generate-docs-reference.js` already reports this class of problem
("title repeats its category"); that finding is now clear. Regenerated
`reference/commands.md` in the same commit so the generated output
cannot disagree with `package.json`.

Removed `create-gh-workflow.md`. It described the retired
`actions/starter-workflows` templates, while the live command
(`aks.draftWorkflow`) scaffolds via Draft and is documented in
`draft-integration.md`.

`README.md` re-listed all 25 feature pages by hand, a third copy after
SUMMARY.md and features.md. It had drifted: four entries pointed at the
same page under different labels, and the Container Assist sub-pages and
Copilot plugin page were missing. Replaced with pointers to the Features
index and the generated Reference.
@bosesuneha
docs: regenerate reference after Argo CD command rename
7bab4bc 
Rebased onto main, which renamed aks.draftArgoCDDeployment to
"AKS: Create Argo CD Application" in Azure#2353. Regenerated so the
committed reference matches package.json; otherwise
docs:reference:check would fail once Azure#2371 lands.
@bosesuneha
docs: correct factual errors in feature guides
ab76be0 
Each change was verified against package.json, src/, or resources/.

merge-save-kubeconfig
  Merge into Kubeconfig and Save Kubeconfig are not this extension's commands.
  Neither appears in contributes.commands; both come from
  ms-kubernetes-tools.vscode-kubernetes-tools, which is an extensionDependency.
  Page now says so.

draft-integration
  Claimed Draft Dockerfile and Draft Deployment are available from the Command
  Palette. Both are registered in src/extension.ts:147-148 but have no
  contributes.commands entry, so they are unreachable. Rewritten around the
  commands that do exist, including aksDraftValidate, which was undocumented,
  and the pinned Draft version v0.17.14, which was never stated.

container-assist-github-workflow
  All five GitHub Action versions were stale: checkout v4 -> v7.0.0, azure/login
  v2 -> v3.0.0, use-kubelogin v1 -> v1.3, aks-set-context v4 -> v5.0.0,
  k8s-deploy v5 -> v6.0.0.
  Removed the "Annotate namespace" step. No template contains it, and
  workflowTemplate.test.ts:223 asserts it is absent.

container-assist-integration
  Removed the namespace annotations section for the same reason.

container-assist-azure-resources
  "9 role assignments" summed two mutually exclusive paths. The maximum is 5:
  one in stage 1, four in stage 2, where the user-namespace and
  managed-namespace paths cannot both apply.

aks-diagnostics
  Detector list did not match the menu: "Known Issues, Availability and
  Performance" is "Cluster and Control Plane Availability and Performance",
  "Network and Connectivity issues" is "Network Connectivity Issues", and
  Storage was missing.

run-kubectl-command, k8s-api-health-points
  Command labels did not match kubectl.ts: "API Resources" is "Get API
  Resources", "Get Node" is "Get Nodes", and the health checks are "Healthz
  Check", "Livez Check", "Readyz Check". Get All Events was missing from the
  health list. Both pages now show the kubectl command each one runs.

argocd-gitops-integration
  Apply runs with --validate=false, which was omitted. The Copilot integration
  is an Azure AI Agent plugin (argoCDDeploymentPlugin), not a chat skill.

telemetery.md and README.md
  telemetry.enableTelemetry was deprecated in VS Code 1.61; the setting is
  telemetry.telemetryLevel set to off.
@bosesuneha
docs: remove stale and unreferenced screenshots
7228a09 
Deletes 23 images, 100 down to 77, and 12M down to 9.6M.

14 were referenced by no page at all. Five of those were orphaned by the
features.md rewrite, the other nine were already dead.

9 were still referenced but showed the classic cluster menu. The extension
switched to the grouped menu by default in Azure#2168 (2026-05-30) and every one of
these was last touched before that, the newest in 2025-07-28. They told readers
to look for menu items that are no longer there. The text breadcrumbs added
earlier in this series replace them, and unlike screenshots those are checked
by docs:check.

Screenshots of webview and result panels are kept. They show output that text
cannot convey, which is the test worth applying: never screenshot a menu path,
screenshot a result.
@bosesuneha
docs: refresh release notes and telemetry, in user-facing terms
7b55ed7 
Release notes stopped at 2.1.0 while the extension shipped 2.4.0, so the
three releases that brought Argo CD on by default, the Kickstart agent
and the Container Assist changes had no reader-facing notes. Added
whats-new-2.4.0.md covering 2.2.0 through 2.4.0 and removed the 2.1.0
file, per the release-pr skill convention of keeping only the current
release. Written around what a reader can now do rather than which
settings changed, and the DevHub removal is left out: that code was
orphaned with no command entry, so no reader can have been using it.

Telemetry is a privacy page and had three accuracy problems:
- Webview panels emit an event per message (BasePanel.ts:162-164),
  which was not disclosed at all.
- clusterCreationSuccess was listed under the Copilot handlers, but
  CreateClusterPanel.ts:300 selects the plain `command` event for the
  normal Create Cluster flow.
- README.md and telemetery.md disclosed different data.
Rewritten so the disclosure is in terms a reader can check, rather than
internal event shapes and type names, with "what we do not collect"
spelled out as concrete categories and the opt-out ahead of the legal
links. README.md now agrees with it.

Wording elsewhere described the extension from the perspective of the
people building it:
- "Feature flag" sections gave instructions for enabling settings that
  are already on by default. Reframed around turning the feature off,
  which is the decision a reader actually faces.
- The menu page documented the default layout as opt-in and referred to
  "the new menu", a comparison a new reader cannot make.
- "the SDK", "the scaffolder" and "Webview" replaced with what those
  are from the outside.
- Container Assist was titled "Alpha Preview" while SUMMARY, the feature
  index and the command titles all say "Preview".
- Three images shared the alt text "Cloud explorer extension menu".

book.toml declares the mdbook-toc preprocessor but no page used the
marker, so the build depended on that binary for nothing. Added
<!-- toc --> to the two pages long enough to need one.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@bosesuneha